From 45713a326ce428168b01ea12cde15c3e9461b086 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Wed, 28 Oct 2026 13:21:11 -0500 Subject: [PATCH] feat(ai): freeform tools (#59963) --- packages/ai/README.md | 21 ++ packages/ai/src/effect.ts | 1 + packages/ai/src/index.ts | 4 +- packages/ai/src/protocols/meta-responses.ts | 6 +- packages/ai/src/protocols/open-responses.ts | 168 +++++++--- packages/ai/src/protocols/openai-chat.ts | 197 ++++++++--- packages/ai/src/protocols/openai-freeform.ts | 94 ++++++ packages/ai/src/protocols/openai-responses.ts | 28 +- packages/ai/src/protocols/venice-chat.ts | 2 +- packages/ai/src/protocols/xai-responses.ts | 3 +- packages/ai/src/schema/messages.ts | 21 ++ packages/ai/src/tool.ts | 39 ++- packages/ai/test/openai-freeform.test.ts | 76 +++++ .../ai/test/provider/freeform-tools.test.ts | 312 ++++++++++++++++++ packages/ai/test/tool.types.ts | 42 +++ 15 files changed, 914 insertions(+), 100 deletions(-) create mode 100644 packages/ai/src/protocols/openai-freeform.ts create mode 100644 packages/ai/test/openai-freeform.test.ts create mode 100644 packages/ai/test/provider/freeform-tools.test.ts diff --git a/packages/ai/README.md b/packages/ai/README.md index 7c052afa7cf..09cbe792809 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -81,6 +81,27 @@ for await (const event of events) { } ``` +### Freeform tools + +A tool with exactly one required string parameter can set `freeform`, so the model writes that parameter as raw text +instead of JSON arguments: unconstrained `text`, or text matching a `regex` or `lark` grammar. + +```ts +const run_code = AI.tool({ + description: "Run JavaScript", + parameters: Schema.Struct({ code: Schema.String }), + freeform: { type: "lark", grammar: JS_GRAMMAR }, + execute: ({ code }) => runCode(code), +}) +``` + +OpenAI Responses and Chat Completions, and every provider that reuses them, send it as a +[custom tool](https://platform.openai.com/docs/guides/function-calling#custom-tools). Other protocols send the normal +JSON tool. Only set `freeform` for models that accept custom tools in that format; nothing checks this or falls back +to JSON, so an unsupported model returns the provider's error. Calls, tool input events, results and history always +use the `{ code }` object, and past calls replay the way the tool is declared in the current request, so the same +history works with or without `freeform`. + ### Structured output `generateObject` forces a tool call and decodes its input against `schema`; pass `jsonSchema` instead for an diff --git a/packages/ai/src/effect.ts b/packages/ai/src/effect.ts index 97ec8a5c585..be732ba346a 100644 --- a/packages/ai/src/effect.ts +++ b/packages/ai/src/effect.ts @@ -43,6 +43,7 @@ export { EffortPart, ContentPart, Message, + Freeform, ToolDefinition, ToolNamespace, ToolEntry, diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts index b033261270b..dd6233735f8 100644 --- a/packages/ai/src/index.ts +++ b/packages/ai/src/index.ts @@ -21,7 +21,7 @@ import { type TranscriptionRequest, type TranscriptionRequestInput, } from "./transcription.js" -import { Tool, ToolFailure, type ToolExecuteContext, type ToolSchema } from "./tool.js" +import { Tool, ToolFailure, type FreeformOption, type ToolExecuteContext, type ToolSchema } from "./tool.js" import { fileMediaType } from "./utils/media-type.js" import { Video, type VideoModel, type VideoRequest, type VideoRequestInput } from "./video.js" @@ -246,6 +246,7 @@ const fileError = (message: string, cause: unknown) => export const tool = >(config: { readonly description: string readonly parameters: Parameters + readonly freeform?: FreeformOption readonly execute: ( params: Schema.Schema.Type, context: Partial & { readonly signal: AbortSignal }, @@ -255,6 +256,7 @@ export const tool = >(config: { description: config.description, parameters: config.parameters, success: Schema.Unknown, + freeform: config.freeform, execute: (params, context) => Effect.tryPromise({ try: async (signal) => (await config.execute(params, { ...context, signal })) ?? null, diff --git a/packages/ai/src/protocols/meta-responses.ts b/packages/ai/src/protocols/meta-responses.ts index eb9898976b3..cfaf7f610ec 100644 --- a/packages/ai/src/protocols/meta-responses.ts +++ b/packages/ai/src/protocols/meta-responses.ts @@ -120,8 +120,10 @@ const fromRequest = Effect.fn("MetaResponses.fromRequest")(function* (request: L type InputItem = OpenResponses.OpenResponsesBody["input"][number] // Hosted replay items have an open `type`, so a plain tag check does not narrow the union. -const isFunctionCallOutput = (item: InputItem): item is Extract => - item.type === "function_call_output" +const isFunctionCallOutput = ( + item: InputItem, +): item is Extract => + item.type === "function_call_output" || item.type === "custom_tool_call_output" const HOSTED_TOOLS = { web_search_call: { name: "web_search", input: (item) => item.action ?? {} }, diff --git a/packages/ai/src/protocols/open-responses.ts b/packages/ai/src/protocols/open-responses.ts index 560d4ca8b06..7e5b54126f1 100644 --- a/packages/ai/src/protocols/open-responses.ts +++ b/packages/ai/src/protocols/open-responses.ts @@ -32,6 +32,7 @@ import { effortUpdate } from "../effort-updates.js" import { OpenResponsesOptions } from "./utils/open-responses-options.js" import { Lifecycle } from "./utils/lifecycle.js" import { ToolStream } from "./utils/tool-stream.js" +import { OpenAIFreeform } from "./openai-freeform.js" const ADAPTER = "open-responses" const NAME = "Open Responses" @@ -217,10 +218,17 @@ export const InputItem = Schema.Union([ arguments: Schema.String, }), Schema.Struct({ - type: Schema.tag("function_call_output"), + type: Schema.Literals(["function_call_output", "custom_tool_call_output"]), call_id: Schema.String, output: OpenResponsesFunctionCallOutput, }), + Schema.Struct({ + type: Schema.tag("custom_tool_call"), + id: Schema.optionalKey(Schema.String), + call_id: Schema.String, + name: Schema.String, + input: Schema.String, + }), HostedToolItem, HostedToolReplay, ]) @@ -242,6 +250,20 @@ export const Tool = Schema.Struct({ strict: Schema.optional(Schema.Boolean), }) +export const CustomTool = Schema.Struct({ + type: Schema.tag("custom"), + name: Schema.String, + description: Schema.String, + format: Schema.Union([ + Schema.Struct({ type: Schema.tag("text") }), + Schema.Struct({ + type: Schema.tag("grammar"), + syntax: Schema.Literals(["lark", "regex"]), + definition: Schema.String, + }), + ]), +}) + export const HostedTool = Schema.StructWithRest( Schema.Struct({ type: Schema.String, @@ -250,13 +272,15 @@ export const HostedTool = Schema.StructWithRest( ) export type HostedTool = Schema.Schema.Type +const NamedTool = Schema.Struct({ type: Schema.Literals(["function", "custom"]), name: Schema.String }) + export const ToolChoice = Schema.Union([ Schema.Literals(["auto", "none", "required"]), - Schema.Struct({ type: Schema.tag("function"), name: Schema.String }), + NamedTool, Schema.Struct({ type: Schema.tag("allowed_tools"), mode: Schema.Literals(["auto", "none", "required"]), - tools: Schema.Array(Schema.Struct({ type: Schema.tag("function"), name: Schema.String })), + tools: Schema.Array(NamedTool), }), ]) @@ -268,7 +292,7 @@ export const coreFields = { model: Schema.String, input: Schema.Array(InputItem), instructions: Schema.optional(Schema.String), - tools: optionalArray(Schema.Union([Tool, HostedTool])), + tools: optionalArray(Schema.Union([Tool, CustomTool, HostedTool])), tool_choice: Schema.optional(ToolChoice), store: Schema.optional(Schema.Boolean), metadata: Schema.optional(Schema.Record(Schema.String, Schema.String)), @@ -420,6 +444,7 @@ export interface ParserState { readonly name: string readonly providerMetadataKey: string readonly tools: ToolStream.State + readonly custom: ReadonlyMap readonly hasFunctionCall: boolean readonly lifecycle: Lifecycle.State readonly outputItems: Readonly> @@ -457,19 +482,45 @@ export const lowerTool = Effect.fnUntraced(function* (protocolName: string, tool } }) -export const lowerTools = (tools: ReadonlyArray, adapter: ProviderAdapter) => +export const lowerCustomTool = (tool: ToolDefinition, custom: OpenAIFreeform.Custom) => { + const grammar = OpenAIFreeform.grammar(custom.format) + return { + type: "custom" as const, + name: tool.name, + description: tool.description, + format: grammar ? { type: "grammar" as const, ...grammar } : { type: "text" as const }, + } +} + +export const lowerTools = ( + tools: ReadonlyArray, + adapter: ProviderAdapter, + custom: ReadonlyMap, +) => Effect.forEach( tools, - (tool): Effect.Effect | HostedTool, AIError> => - tool.native !== undefined && adapter.nativeTool ? adapter.nativeTool(tool.native) : lowerTool(adapter.name, tool), + (tool): Effect.Effect | HostedTool, AIError> => { + if (tool.native !== undefined && adapter.nativeTool) return adapter.nativeTool(tool.native) + const definition = custom.get(tool.name) + return definition ? Effect.succeed(lowerCustomTool(tool, definition)) : lowerTool(adapter.name, tool) + }, ) -export const lowerToolChoice = (protocolName: string, toolChoice: NonNullable) => +export const namedTool = (name: string, custom: ReadonlyMap) => ({ + type: custom.has(name) ? ("custom" as const) : ("function" as const), + name, +}) + +export const lowerToolChoice = ( + protocolName: string, + toolChoice: NonNullable, + custom: ReadonlyMap, +) => ProviderShared.matchToolChoice(protocolName, toolChoice, { auto: () => "auto" as const, none: () => "none" as const, required: () => "required" as const, - tool: (toolName) => ({ type: "function" as const, name: toolName }), + tool: (toolName) => namedTool(toolName, custom), }) // Server-issued item ids need a nonempty prefix and suffix, but the prefix is @@ -481,8 +532,23 @@ const itemID = (providerMetadata: ProviderMetadata | undefined, providerMetadata return separator > 0 && separator < metadata.itemId.length - 1 ? metadata.itemId : undefined } -const lowerToolCall = (part: ToolCallPart, providerMetadataKey: string): OpenResponsesInputItem => { - const id = itemID(part.providerMetadata, providerMetadataKey) +// A call replays as the type its tool is declared with now; the item id only survives when that type is unchanged. +const lowerToolCall = ( + part: ToolCallPart, + providerMetadataKey: string, + custom: OpenAIFreeform.Custom | undefined, +): OpenResponsesInputItem => { + const id = OpenAIFreeform.keepsItemID(part.providerMetadata, providerMetadataKey, custom !== undefined) + ? itemID(part.providerMetadata, providerMetadataKey) + : undefined + if (custom) + return { + type: "custom_tool_call", + ...(id === undefined ? {} : { id }), + call_id: part.id, + name: part.name, + input: OpenAIFreeform.toRaw(custom, part.input), + } return { type: "function_call", ...(id === undefined ? {} : { id }), @@ -580,6 +646,9 @@ const lowerMessages = Effect.fnUntraced(function* ( ) { const input: OpenResponsesInputItem[] = [] const providerMetadataKey = metadataKey(request.model) + const custom = OpenAIFreeform.tools(request) + const customTool = (part: ToolCallPart | ToolResultPart) => + part.namespace === undefined ? custom.get(part.name) : undefined for (const message of request.messages) { const rawMetadata = message.providerMetadata?.[providerMetadataKey] @@ -671,7 +740,7 @@ const lowerMessages = Effect.fnUntraced(function* ( if (part.type === "tool-call") { flushText() if (part.providerExecuted === true) continue - input.push(lowerToolCall(part, providerMetadataKey)) + input.push(lowerToolCall(part, providerMetadataKey, customTool(part))) continue } if (part.type === "tool-result" && part.providerExecuted === true) { @@ -727,7 +796,7 @@ const lowerMessages = Effect.fnUntraced(function* ( if (!ProviderShared.supportsContent(part, ["tool-result"])) return yield* ProviderShared.unsupportedContent(adapter.name, "tool", ["tool-result"]) input.push({ - type: "function_call_output", + type: customTool(part) ? "custom_tool_call_output" : "function_call_output", call_id: part.id, output: yield* lowerToolResultOutput(part, request, adapter), }) @@ -787,13 +856,16 @@ export const resolveParallelToolCalls = (request: LLMRequest, options = OpenResp return disabled === undefined ? undefined : !disabled } -export const allowedToolChoice = (request: LLMRequest, options = OpenResponsesOptions.resolve(request)) => { +export const allowedToolChoice = ( + options: OpenResponsesOptions.Resolved, + custom: ReadonlyMap, +) => { const allowed = options.allowedTools if (!allowed) return undefined return { type: "allowed_tools" as const, mode: allowed.mode, - tools: allowed.toolNames.map((name) => ({ type: "function" as const, name })), + tools: allowed.toolNames.map((name) => namedTool(name, custom)), } } @@ -803,13 +875,14 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd ) { const projected = ProviderShared.flattenToolRequest(request) const options = OpenResponsesOptions.resolve(request) + const custom = OpenAIFreeform.tools(request) return { ...(yield* lowerConversation(projected.request, adapter)), ...lowerGeneration(request, options), - tools: projected.tools.length === 0 ? undefined : yield* lowerTools(projected.tools, adapter), + tools: projected.tools.length === 0 ? undefined : yield* lowerTools(projected.tools, adapter, custom), tool_choice: - allowedToolChoice(request, options) ?? - (request.toolChoice ? yield* lowerToolChoice(adapter.name, request.toolChoice) : undefined), + allowedToolChoice(options, custom) ?? + (request.toolChoice ? yield* lowerToolChoice(adapter.name, request.toolChoice, custom) : undefined), } }) @@ -909,6 +982,7 @@ const ITEM_ID_PREFIX: Readonly> = { message: "msg", reasoning: "rs", function_call: "fc", + custom_tool_call: "ctc", compaction: "cmp", } @@ -1069,23 +1143,24 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu events, ] } - if (item.type !== "function_call" || !item.call_id) return [state, NO_EVENTS] + if ((item.type !== "function_call" && item.type !== "custom_tool_call") || !item.call_id) return [state, NO_EVENTS] if (state.tools[item.id] !== undefined) return [state, NO_EVENTS] - const metadata = providerMetadata(state, { itemId: item.id }) + const custom = item.type === "custom_tool_call" + const metadata = providerMetadata(state, OpenAIFreeform.metadata(item.id, custom)) const events: LLMEvent[] = [] const lifecycle = Lifecycle.stepStart(state.lifecycle, events) + const tools = ToolStream.start(state.tools, item.id, { + id: item.call_id, + name: item.name ?? "", + namespace: item.namespace, + input: custom ? "" : (item.arguments ?? ""), + providerMetadata: metadata, + }) + const opened = custom + ? ToolStream.append(tools, item.id, OpenAIFreeform.streamStart(state.custom.get(item.name ?? ""), rawInput(item))) + : undefined return [ - { - ...state, - lifecycle, - tools: ToolStream.start(state.tools, item.id, { - id: item.call_id, - name: item.name ?? "", - namespace: item.namespace, - input: item.arguments ?? "", - providerMetadata: metadata, - }), - }, + { ...state, lifecycle, tools: opened?.tools ?? tools }, [ ...events, LLMEvent.toolInputStart({ @@ -1094,10 +1169,13 @@ const onOutputItemAdded = (state: ParserState, event: NormalizedEvent): StepResu namespace: item.namespace, providerMetadata: metadata, }), + ...(opened?.events ?? []), ], ] } +const rawInput = (item: OutputItem) => (typeof item.input === "string" ? item.input : "") + const onReasoningSummaryPartAdded = (state: ParserState, event: Event): StepResult => { if (event.item_id === undefined || event.summary_index === undefined) return [state, NO_EVENTS] return startReasoningSummaryPart(state, event.item_id, event.summary_index) @@ -1207,12 +1285,16 @@ const onOutputItemDone = Effect.fnUntraced(function* ( ] satisfies StepResult } - if (item.type === "function_call") { + if (item.type === "function_call" || item.type === "custom_tool_call") { if (!item.call_id || !item.name) return [state, NO_EVENTS] satisfies StepResult - const metadata = providerMetadata(state, { itemId: item.id }) + const custom = item.type === "custom_tool_call" + const metadata = providerMetadata(state, OpenAIFreeform.metadata(item.id, custom)) + const final = { custom: state.custom.get(item.name), raw: rawInput(item) } + const input = custom ? OpenAIFreeform.fromRaw(final.custom, final.raw) : item.arguments const registered = state.tools[item.id] !== undefined + const closed = custom ? OpenAIFreeform.close(state.tools, [item.id], final) : undefined const tools = registered - ? state.tools + ? (closed?.tools ?? state.tools) : ToolStream.start(state.tools, item.id, { id: item.call_id, name: item.name, @@ -1220,11 +1302,11 @@ const onOutputItemDone = Effect.fnUntraced(function* ( providerMetadata: metadata, }) const result = - item.arguments === undefined + input === undefined ? yield* ToolStream.finish(state.id, tools, item.id) - : yield* ToolStream.finishWithInput(state.id, tools, item.id, item.arguments) + : yield* ToolStream.finishWithInput(state.id, tools, item.id, input) const events: LLMEvent[] = [] - const finished = result.events ?? [] + const finished = [...(closed?.events ?? []), ...(result.events ?? [])] // A done-only call never streamed a start event, so open its lifecycle here. const resultEvents = registered || finished.length === 0 @@ -1306,7 +1388,8 @@ const onResponseFinish = Effect.fnUntraced(function* (state: ParserState, event: "Cannot recover a compaction checkpoint after output has been emitted", ) const recoverable = - item.type === "compaction" || (item.type === "function_call" && current.tools[item.id] !== undefined) + item.type === "compaction" || + ((item.type === "function_call" || item.type === "custom_tool_call") && current.tools[item.id] !== undefined) if (!recoverable) continue const [next, emitted] = yield* onOutputItemDone(current, item) current = next @@ -1434,6 +1517,14 @@ export const step = (state: ParserState, event: NormalizedEvent) => { return event.item_id !== undefined ? onFunctionCallArgumentsDelta(state, event) : ProviderShared.eventError(state.id, `${event.type} is missing item_id`) + if (event.type === "response.custom_tool_call_input.delta") + return event.item_id !== undefined + ? onFunctionCallArgumentsDelta(state, { + ...event, + type: "response.function_call_arguments.delta", + delta: OpenAIFreeform.streamDelta(event.delta ?? ""), + }) + : ProviderShared.eventError(state.id, `${event.type} is missing item_id`) if (event.type === "response.output_item.done") return onOutputItemDone(state, event.item) if (event.type === "response.completed" || event.type === "response.incomplete") return onResponseFinish(state, event) if (event.type === "response.failed") return providerFailure(event, `${state.name} response failed`) @@ -1456,6 +1547,7 @@ export const initial = (request: LLMRequest, adapter: ProviderAdapter = BASE_ADA providerMetadataKey: metadataKey(request.model), hasFunctionCall: false, tools: ToolStream.empty(), + custom: OpenAIFreeform.tools(request), lifecycle: Lifecycle.initial(), outputItems: {}, message: undefined, diff --git a/packages/ai/src/protocols/openai-chat.ts b/packages/ai/src/protocols/openai-chat.ts index 6e651c5a845..111a9a16b79 100644 --- a/packages/ai/src/protocols/openai-chat.ts +++ b/packages/ai/src/protocols/openai-chat.ts @@ -30,6 +30,7 @@ import { resolveParallelToolCalls } from "./open-responses.js" import { OpenResponsesOptions } from "./utils/open-responses-options.js" import { Lifecycle } from "./utils/lifecycle.js" import { ToolStream } from "./utils/tool-stream.js" +import { OpenAIFreeform } from "./openai-freeform.js" const ADAPTER = "openai-chat" const RESERVED_REASONING_FIELDS = new Set(["role", "content", "refusal", "tool_calls"]) @@ -48,16 +49,33 @@ const OpenAIChatCacheControl = Schema.Struct({ }) type OpenAIChatCacheControl = Schema.Schema.Type -const OpenAIChatTool = Schema.Struct({ - type: Schema.tag("function"), - function: Schema.Struct({ - name: Schema.String, - description: Schema.String, - parameters: JsonObject, - strict: Schema.optional(Schema.Boolean), +const OpenAIChatTool = Schema.Union([ + Schema.Struct({ + type: Schema.tag("function"), + function: Schema.Struct({ + name: Schema.String, + description: Schema.String, + parameters: JsonObject, + strict: Schema.optional(Schema.Boolean), + }), + cache_control: Schema.optional(OpenAIChatCacheControl), }), - cache_control: Schema.optional(OpenAIChatCacheControl), -}) + Schema.Struct({ + type: Schema.tag("custom"), + custom: Schema.Struct({ + name: Schema.String, + description: Schema.String, + format: Schema.Union([ + Schema.Struct({ type: Schema.tag("text") }), + Schema.Struct({ + type: Schema.tag("grammar"), + grammar: Schema.Struct({ syntax: Schema.Literals(["lark", "regex"]), definition: Schema.String }), + }), + ]), + }), + cache_control: Schema.optional(OpenAIChatCacheControl), + }), +]) type OpenAIChatTool = Schema.Schema.Type // Gemini's OpenAI-compatible surface carries thought signatures in tool call @@ -77,7 +95,18 @@ export const OpenAIChatAssistantToolCall = Schema.Struct({ }), extra_content: Schema.optional(ExtraContent), }) -type OpenAIChatAssistantToolCall = Schema.Schema.Type + +export const OpenAIChatAssistantCustomToolCall = Schema.Struct({ + id: Schema.String, + type: Schema.tag("custom"), + custom: Schema.Struct({ + name: Schema.String, + input: Schema.String, + }), +}) +type OpenAIChatAssistantToolCall = Schema.Schema.Type< + typeof OpenAIChatAssistantToolCall | typeof OpenAIChatAssistantCustomToolCall +> // `reasoning_details` carries two dialects. OpenRouter's `reasoning.*` entries // must be replayed unmodified (`index` included), so they keep every field they @@ -154,7 +183,7 @@ export const OpenAIChatMessage = Schema.Union([ Schema.Struct({ role: Schema.Literal("assistant"), content: Schema.NullOr(Schema.Union([Schema.String, Schema.Array(OpenAIChatTextContent)])), - tool_calls: optionalArray(OpenAIChatAssistantToolCall), + tool_calls: optionalArray(Schema.Union([OpenAIChatAssistantToolCall, OpenAIChatAssistantCustomToolCall])), reasoning_content: Schema.optional(Schema.String), reasoning: Schema.optional(Schema.String), reasoning_text: Schema.optional(Schema.String), @@ -176,6 +205,10 @@ const OpenAIChatToolChoice = Schema.Union([ type: Schema.tag("function"), function: Schema.Struct({ name: Schema.String }), }), + Schema.Struct({ + type: Schema.tag("custom"), + custom: Schema.Struct({ name: Schema.String }), + }), ]) export const bodyFields = { @@ -256,6 +289,7 @@ export const OpenAIChatToolCallDelta = Schema.Struct({ index: optionalNull(Schema.Number), id: optionalNull(Schema.String), function: optionalNull(OpenAIChatToolCallDeltaFunction), + custom: optionalNull(Schema.Struct({ name: optionalNull(Schema.String), input: optionalNull(Schema.String) })), extra_content: optionalNull(Schema.Unknown), }) type OpenAIChatToolCallDelta = Schema.Schema.Type @@ -315,6 +349,9 @@ interface PendingToolDelta { export interface ParserState { readonly providerMetadataKey: string readonly tools: ToolStream.State + readonly custom: ReadonlyMap + /** Stream indexes of custom tool calls, whose JSON fragment closes when the call finishes. */ + readonly customCalls: ReadonlySet readonly pendingTools: Partial> readonly toolCallEvents: ReadonlyArray readonly usage?: Usage @@ -344,37 +381,74 @@ interface LoweringOptions { readonly assistant?: (source: LLMRequest["messages"][number], message: OpenAIChatMessage) => OpenAIChatMessage } -const lowerTool = (tool: ToolDefinition, options: LoweringOptions, supportsStrictMode: boolean): OpenAIChatTool => ({ - type: "function", - function: { - name: tool.name, - description: tool.description, - parameters: tool.inputSchema, - ...(supportsStrictMode ? { strict: false } : {}), - }, - cache_control: options.cacheControl?.(tool.cache), -}) +type MessageLoweringOptions = LoweringOptions & { + readonly providerMetadataKey: string + readonly custom: ReadonlyMap +} -const lowerToolChoice = (toolChoice: NonNullable) => +const lowerTool = ( + tool: ToolDefinition, + options: LoweringOptions, + supportsStrictMode: boolean, + custom: OpenAIFreeform.Custom | undefined, +): OpenAIChatTool => { + if (custom) { + const grammar = OpenAIFreeform.grammar(custom.format) + return { + type: "custom", + custom: { + name: tool.name, + description: tool.description, + format: grammar ? { type: "grammar", grammar } : { type: "text" }, + }, + cache_control: options.cacheControl?.(tool.cache), + } + } + return { + type: "function", + function: { + name: tool.name, + description: tool.description, + parameters: tool.inputSchema, + ...(supportsStrictMode ? { strict: false } : {}), + }, + cache_control: options.cacheControl?.(tool.cache), + } +} + +const lowerToolChoice = ( + toolChoice: NonNullable, + custom: ReadonlyMap, +) => ProviderShared.matchToolChoice("OpenAI Chat", toolChoice, { auto: () => "auto" as const, none: () => "none" as const, required: () => "required" as const, - tool: (name) => ({ type: "function" as const, function: { name } }), + tool: (name) => + custom.has(name) + ? { type: "custom" as const, custom: { name } } + : { type: "function" as const, function: { name } }, }) -const lowerToolCall = ( - part: ToolCallPart, - options: LoweringOptions & { readonly providerMetadataKey: string }, -): OpenAIChatAssistantToolCall => ({ - id: options.toolCallID?.(part.id) ?? part.id, - type: "function", - function: { - name: part.name, - arguments: ProviderShared.encodeJson(part.input === undefined ? {} : part.input), - }, - extra_content: decodeExtraContent(part.providerMetadata?.[options.providerMetadataKey]?.extraContent), -}) +// A call replays as the type its tool is declared with in this request. +const lowerToolCall = (part: ToolCallPart, options: MessageLoweringOptions): OpenAIChatAssistantToolCall => { + const custom = options.custom.get(part.name) + if (custom) + return { + id: options.toolCallID?.(part.id) ?? part.id, + type: "custom", + custom: { name: part.name, input: OpenAIFreeform.toRaw(custom, part.input) }, + } + return { + id: options.toolCallID?.(part.id) ?? part.id, + type: "function", + function: { + name: part.name, + arguments: ProviderShared.encodeJson(part.input === undefined ? {} : part.input), + }, + extra_content: decodeExtraContent(part.providerMetadata?.[options.providerMetadataKey]?.extraContent), + } +} const lowerMedia = Effect.fnUntraced(function* (part: MediaPart) { // Chat Completions accepts PDFs, and no other documents, as inline `file` parts; file URLs are not supported. @@ -451,7 +525,7 @@ const lowerAssistantMessage = Effect.fnUntraced(function* ( message: OpenAIChatRequestMessage, configuredField: string | undefined, requireReasoning: boolean, - options: LoweringOptions & { readonly providerMetadataKey: string }, + options: MessageLoweringOptions, ) { const content: OpenAIChatTextContent[] = [] const reasoning: ReasoningPart[] = [] @@ -553,7 +627,7 @@ const lowerMessage = Effect.fnUntraced(function* ( message: OpenAIChatRequestMessage, reasoningField: string | undefined, requireReasoning: boolean, - options: LoweringOptions & { readonly providerMetadataKey: string }, + options: MessageLoweringOptions, ) { if (message.role === "user") return [yield* lowerUserMessage(message, options)] if (message.role === "assistant") { @@ -563,7 +637,10 @@ const lowerMessage = Effect.fnUntraced(function* ( return (yield* lowerToolMessages(message, options)).messages }) -const lowerMessages = Effect.fnUntraced(function* (request: LLMRequest, options: LoweringOptions) { +const lowerMessages = Effect.fnUntraced(function* ( + request: LLMRequest, + options: Omit, +) { const system: OpenAIChatMessage[] = request.system.length === 0 ? [] @@ -817,7 +894,8 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* ( request.model.compatibility?.zaiToolStream ?? detectZaiToolStream(provider, baseURL, request.model.id) const hasHistory = hasToolHistory(request.messages) const hasActiveTools = flattened.tools.length > 0 - const lowering = { ...options, cacheControl: options.cacheControl ?? declaredCacheControl(request) } + const custom = OpenAIFreeform.tools(request) + const lowering = { ...options, cacheControl: options.cacheControl ?? declaredCacheControl(request), custom } return { model: request.model.id, messages: yield* lowerMessages(flattened.request, lowering), @@ -826,8 +904,8 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* ( ? hasHistory ? [] : undefined - : flattened.tools.map((tool) => lowerTool(tool, lowering, supportsStrictMode)), - tool_choice: hasActiveTools && request.toolChoice ? yield* lowerToolChoice(request.toolChoice) : undefined, + : flattened.tools.map((tool) => lowerTool(tool, lowering, supportsStrictMode, custom.get(tool.name))), + tool_choice: hasActiveTools && request.toolChoice ? yield* lowerToolChoice(request.toolChoice, custom) : undefined, stream: true as const, ...((request.model.compatibility?.streamUsage ?? true) ? { stream_options: { include_usage: true } } : {}), ...(zaiToolStream && hasActiveTools ? { tool_stream: true } : {}), @@ -1062,6 +1140,7 @@ const step = (state: ParserState, event: OpenAIChatEvent) => const toolDeltas = delta?.tool_calls ?? [] let tools = state.tools let pendingTools = state.pendingTools + let customCalls = state.customCalls let latestToolIndex = state.latestToolIndex let nextToolIndex = state.nextToolIndex @@ -1070,7 +1149,13 @@ const step = (state: ParserState, event: OpenAIChatEvent) => const reasoning = reasoningDelta(delta, state.reasoningField) if ( state.finishReason !== undefined && - toolDeltas.some((tool) => Boolean(tool.id) || Boolean(tool.function?.name) || Boolean(tool.function?.arguments)) + toolDeltas.some( + (tool) => + Boolean(tool.id) || + Boolean(tool.function?.name) || + Boolean(tool.function?.arguments) || + Boolean(tool.custom?.input), + ) ) return yield* ProviderShared.eventError( ADAPTER, @@ -1116,8 +1201,17 @@ const step = (state: ParserState, event: OpenAIChatEvent) => const current = tools[index] const pending = pendingTools[index] const id = current?.id ?? pending?.id ?? (tool.id || undefined) - const name = current?.name ?? pending?.name ?? (tool.function?.name || undefined) - const text = `${pending?.input ?? ""}${tool.function?.arguments ?? ""}` + const name = current?.name ?? pending?.name ?? (tool.function?.name || tool.custom?.name || undefined) + // Custom calls stream raw text; re-encode it as JSON arguments for the call's field. + const opening = Boolean(tool.custom) && !customCalls.has(index) + if (opening) customCalls = new Set([...customCalls, index]) + const raw = tool.custom?.input ?? "" + const fragment = tool.custom + ? opening + ? OpenAIFreeform.streamStart(state.custom.get(name ?? ""), raw) + : OpenAIFreeform.streamDelta(raw) + : (tool.function?.arguments ?? "") + const text = `${pending?.input ?? ""}${fragment}` const extraContent = pending?.extraContent ?? decodeExtraContent(tool.extra_content) latestToolIndex = index nextToolIndex = Math.max(nextToolIndex, index + 1) @@ -1177,13 +1271,15 @@ const step = (state: ParserState, event: OpenAIChatEvent) => !incompleteTools && state.finishReason === undefined && Object.keys(tools).length > 0 - ? yield* ToolStream.finishAll(ADAPTER, tools) + ? yield* finishTools(tools, customCalls) : undefined return [ { providerMetadataKey: state.providerMetadataKey, tools: finished?.tools ?? tools, + custom: state.custom, + customCalls, pendingTools, toolCallEvents: finished?.events ?? state.toolCallEvents, usage, @@ -1202,6 +1298,13 @@ const step = (state: ParserState, event: OpenAIChatEvent) => ] as const }) +// Custom calls close their JSON fragment before every pending call finishes. +const finishTools = Effect.fnUntraced(function* (tools: ParserState["tools"], customCalls: ReadonlySet) { + const closed = OpenAIFreeform.close(tools, customCalls) + const finished = yield* ToolStream.finishAll(ADAPTER, closed.tools) + return { tools: finished.tools, events: [...closed.events, ...finished.events] } +}) + export const finishEvents = Effect.fnUntraced(function* (state: ParserState) { if (state.finishReason === undefined && state.requireFinishReason) return yield* new AIError({ @@ -1214,7 +1317,7 @@ export const finishEvents = Effect.fnUntraced(function* (state: ParserState) { const events: LLMEvent[] = [] const toolCallEvents = state.finishReason === undefined && Object.keys(state.tools).length > 0 - ? (yield* ToolStream.finishAll(ADAPTER, state.tools)).events + ? (yield* finishTools(state.tools, state.customCalls)).events : state.toolCallEvents const hasToolCalls = toolCallEvents.length > 0 const reason = state.finishReason @@ -1267,6 +1370,8 @@ export const protocol = Protocol.make({ initial: (request) => ({ providerMetadataKey: request.model.route.providerMetadataKey ?? request.model.provider, tools: ToolStream.empty(), + custom: OpenAIFreeform.tools(request), + customCalls: new Set(), pendingTools: {}, toolCallEvents: [], lifecycle: Lifecycle.initial(), diff --git a/packages/ai/src/protocols/openai-freeform.ts b/packages/ai/src/protocols/openai-freeform.ts new file mode 100644 index 00000000000..272827f7c93 --- /dev/null +++ b/packages/ai/src/protocols/openai-freeform.ts @@ -0,0 +1,94 @@ +import { Option, Schema } from "effect" +import { + ToolDefinition, + type Freeform, + type LLMEvent, + type LLMRequest, + type ProviderMetadata, +} from "../schema/index.js" +import { encodeJson, flattenTools, isRecord } from "./shared.js" +import { ToolStream } from "./utils/tool-stream.js" + +// Freeform tools as OpenAI custom tools, shared by Responses and Chat Completions: +// https://platform.openai.com/docs/guides/function-calling#custom-tools +// Calls keep the normal `{ field: raw }` input everywhere else; only the wire carries raw text. + +export interface Custom { + /** The tool's one required string parameter, which the raw text fills. */ + readonly field: string + readonly format: Freeform +} + +/** How a tool goes out: a custom tool when it declares `freeform` with one required string parameter. */ +export const resolve = (tool: ToolDefinition): Custom | undefined => { + const field = ToolDefinition.freeformField(tool.inputSchema) + if (tool.freeform === undefined || tool.native !== undefined || field === undefined) return undefined + return { field, format: tool.freeform } +} + +/** Custom tools in this request, by flattened tool name. */ +export const tools = (request: LLMRequest): ReadonlyMap => + new Map( + flattenTools(request.tools).flatMap((tool) => { + const custom = resolve(tool) + return custom ? [[tool.name, custom] as const] : [] + }), + ) + +/** The format's grammar, or `undefined` for unconstrained text. */ +export const grammar = (format: Freeform) => + format.type === "text" + ? undefined + : { syntax: format.type, definition: format.type === "regex" ? format.pattern : format.grammar } + +/** Raw text replayed for a past call: its field, or the whole input as JSON when the field is not a string. */ +export const toRaw = (custom: Custom, input: unknown) => { + const value = isRecord(input) ? input[custom.field] : undefined + return typeof value === "string" ? value : encodeJson(input ?? {}) +} + +/** JSON arguments for a raw call. A call to an undeclared custom tool fills `input`. */ +export const fromRaw = (custom: Custom | undefined, raw: string) => encodeJson({ [field(custom)]: raw }) + +const field = (custom: Custom | undefined) => custom?.field ?? "input" + +// Streamed raw text is re-encoded as JSON-argument fragments, so the tool-input events match a JSON tool's. +/** The opening fragment, `{"field":"`, followed by the escaped first text. */ +export const streamStart = (custom: Custom | undefined, raw = "") => + `{${encodeJson(field(custom))}:"${streamDelta(raw)}` +export const streamDelta = (raw: string) => encodeJson(raw).slice(1, -1) +const STREAM_END = '"}' + +const decodeArguments = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown))) + +/** + * Close the JSON fragment of each open custom call. With a `final` raw input, a call only closes when its fragments + * decode to it, so an authoritative final input that disagrees replaces the streamed one instead. + */ +export const close = ( + tools: ToolStream.State, + keys: Iterable, + final?: { readonly custom: Custom | undefined; readonly raw: string }, +) => + [...keys].reduce<{ readonly tools: ToolStream.State; readonly events: ReadonlyArray }>( + (result, key) => { + const pending = result.tools[key] + const streamed = pending && Option.getOrUndefined(decodeArguments(`${pending.input}${STREAM_END}`)) + if (!pending || (final !== undefined && streamed?.[field(final.custom)] !== final.raw)) return result + const appended = ToolStream.append(result.tools, key, STREAM_END) + return appended ? { tools: appended.tools, events: [...result.events, ...appended.events] } : result + }, + { tools, events: [] }, + ) + +/** Provider metadata marking a call that arrived as a custom tool call. */ +export const metadata = (itemId: string, custom: boolean) => (custom ? { itemId, custom: true } : { itemId }) + +/** + * Whether a replayed call keeps its item id: only when it goes out as the type it arrived as, since OpenAI item ids + * name their type (`fc_`, `ctc_`). The `call_id` always survives. + */ +export const keepsItemID = (providerMetadata: ProviderMetadata | undefined, key: string, custom: boolean) => + (providerMetadata?.[key]?.custom === true) === custom + +export * as OpenAIFreeform from "./openai-freeform.js" diff --git a/packages/ai/src/protocols/openai-responses.ts b/packages/ai/src/protocols/openai-responses.ts index 542e9b68fb7..adeeb3c7e00 100644 --- a/packages/ai/src/protocols/openai-responses.ts +++ b/packages/ai/src/protocols/openai-responses.ts @@ -17,6 +17,7 @@ import { OpenResponsesChannel } from "./open-responses-channel.js" import { ResponsesCompaction } from "./utils/responses-compaction.js" import { ResponsesCheckpoint } from "./utils/responses-checkpoint.js" import * as Cache from "./utils/cache.js" +import { OpenAIFreeform } from "./openai-freeform.js" const ADAPTER = "openai-responses" const NAME = "OpenAI Responses" @@ -107,6 +108,7 @@ const OpenAIResponsesNamespace = Schema.Struct({ const OpenAIResponsesTools = Schema.Union([ OpenResponses.Tool, + OpenResponses.CustomTool, OpenAIResponsesNamespace, OpenAIResponsesImageGenerationTool, ]) @@ -181,19 +183,21 @@ const nativeImageTool = (tool: ToolDefinition) => { return Schema.is(OpenAIResponsesImageGenerationTool)(native) ? native : undefined } -const lowerTool = Effect.fnUntraced(function* (tool: ToolDefinition) { +const lowerTool = Effect.fnUntraced(function* (tool: ToolDefinition, custom: ReadonlyMap) { const native = nativeImageToolInput(tool) if (native !== undefined) { if (Schema.is(OpenAIResponsesImageGenerationTool)(native)) return native return yield* ProviderShared.invalidRequest("OpenAI Responses image generation tool options are invalid") } + const definition = custom.get(tool.name) + if (definition) return OpenResponses.lowerCustomTool(tool, definition) return yield* OpenResponses.lowerTool(NAME, tool) }) // Native namespaces hold only function tools, so deeper levels flatten into // the leaf names the same way non-native protocols flatten the whole tree. -const lowerToolEntry = Effect.fnUntraced(function* (tool: ToolEntry) { - if (tool.type === "tool") return yield* lowerTool(tool) +const lowerToolEntry = Effect.fnUntraced(function* (tool: ToolEntry, custom: ReadonlyMap) { + if (tool.type === "tool") return yield* lowerTool(tool, custom) // OpenAI requires a namespace description; fall back to a generic one so a // missing description never blocks the request. return { @@ -206,9 +210,16 @@ const lowerToolEntry = Effect.fnUntraced(function* (tool: ToolEntry) { } }) -const lowerTools = (request: LLMRequest) => Effect.forEach(request.tools, lowerToolEntry) +const lowerTools = (request: LLMRequest) => { + const custom = OpenAIFreeform.tools(request) + return Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, custom)) +} -const lowerToolChoice = (toolChoice: NonNullable, tools: ReadonlyArray) => +const lowerToolChoice = ( + toolChoice: NonNullable, + tools: ReadonlyArray, + custom: ReadonlyMap, +) => ProviderShared.matchToolChoice(NAME, toolChoice, { auto: () => "auto" as const, none: () => "none" as const, @@ -216,7 +227,7 @@ const lowerToolChoice = (toolChoice: NonNullable, tool tool: (name) => tools.some((tool) => tool.type === "tool" && tool.name === name && nativeImageTool(tool) !== undefined) ? ({ type: "image_generation" } as const) - : { type: "function" as const, name }, + : OpenResponses.namedTool(name, custom), }) const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: LLMRequest) { @@ -227,6 +238,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: const reasoning = Schema.decodeUnknownSync(ReasoningOptions)(request.providerOptions ?? {}) const updates = resolveEffortUpdates(request, options.reasoningEffort) const generation = OpenResponses.lowerGeneration(request, { ...options, reasoningEffort: updates.effort }) + const custom = OpenAIFreeform.tools(request) return { ...(yield* OpenResponses.lowerConversation(updates.request, adapter)), ...generation, @@ -245,8 +257,8 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request: tool_choice: request.tools.length === 0 ? undefined - : (OpenResponses.allowedToolChoice(request, options) ?? - (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined)), + : (OpenResponses.allowedToolChoice(options, custom) ?? + (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools, custom) : undefined)), } }) diff --git a/packages/ai/src/protocols/venice-chat.ts b/packages/ai/src/protocols/venice-chat.ts index 3fe448b1f9c..d61f7848a88 100644 --- a/packages/ai/src/protocols/venice-chat.ts +++ b/packages/ai/src/protocols/venice-chat.ts @@ -60,7 +60,7 @@ const ToolCall = Schema.Struct({ const Assistant = Schema.StructWithRest( Schema.Struct({ ...OpenAIChat.OpenAIChatMessage.cases.assistant.schema.fields, - tool_calls: optionalArray(ToolCall), + tool_calls: optionalArray(Schema.Union([ToolCall, OpenAIChat.OpenAIChatAssistantCustomToolCall])), thought_signature: Schema.optional(Schema.String), }), [JsonObject], diff --git a/packages/ai/src/protocols/xai-responses.ts b/packages/ai/src/protocols/xai-responses.ts index 5a580cd8b48..d7e2ec8d79d 100644 --- a/packages/ai/src/protocols/xai-responses.ts +++ b/packages/ai/src/protocols/xai-responses.ts @@ -5,6 +5,7 @@ import { OpenResponses } from "./open-responses.js" import { JsonObject, optionalNull, ProviderShared } from "./shared.js" import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js" import { ResponsesCompaction } from "./utils/responses-compaction.js" +import { OpenAIFreeform } from "./openai-freeform.js" const ADAPTER = "xai-responses" const NAME = "xAI Responses" @@ -115,7 +116,7 @@ export const protocol = Protocol.make({ }) export const compact = ResponsesCompaction.make(adapter, (request) => - OpenResponses.lowerTools(ProviderShared.flattenTools(request.tools), adapter), + OpenResponses.lowerTools(ProviderShared.flattenTools(request.tools), adapter, OpenAIFreeform.tools(request)), ) export * as XAIResponses from "./xai-responses.js" diff --git a/packages/ai/src/schema/messages.ts b/packages/ai/src/schema/messages.ts index ac3bfd451aa..e3fdff89dc4 100644 --- a/packages/ai/src/schema/messages.ts +++ b/packages/ai/src/schema/messages.ts @@ -284,11 +284,23 @@ export namespace Message { make({ role: "tool", content: ["type" in result ? result : ToolResultPart.make(result)] }) } +/** + * Raw-text wire encoding for a tool with exactly one required string parameter. Models that accept the format + * write that parameter's value directly instead of JSON arguments; calls still decode to the normal object input. + */ +export const Freeform = Schema.Union([ + Schema.Struct({ type: Schema.Literal("text") }), + Schema.Struct({ type: Schema.Literal("regex"), pattern: Schema.String }), + Schema.Struct({ type: Schema.Literal("lark"), grammar: Schema.String }), +]).annotate({ identifier: "LLM.Freeform" }) +export type Freeform = Schema.Schema.Type + const toolDefinitionFields = { name: Schema.String, description: Schema.String, inputSchema: JsonSchema, outputSchema: Schema.optional(JsonSchema), + freeform: Schema.optional(Freeform), cache: Schema.optional(CacheHint), metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)), native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)), @@ -310,6 +322,15 @@ export namespace ToolDefinition { /** Normalize tool definition input into the canonical `ToolDefinition` class. */ export const make = (input: Input) => (input instanceof ToolDefinition ? input : new ToolDefinition(input)) + + /** The parameter a freeform call fills: the input schema's only property, when it is a required string. */ + export const freeformField = (schema: JsonSchema) => { + const properties = Object.entries(Schema.is(JsonSchema)(schema.properties) ? schema.properties : {}) + if (properties.length !== 1) return undefined + const [name, property] = properties[0] + if (!Schema.is(JsonSchema)(property) || property.type !== "string") return undefined + return Array.isArray(schema.required) && schema.required.includes(name) ? name : undefined + } } export type ToolNamespace = { diff --git a/packages/ai/src/tool.ts b/packages/ai/src/tool.ts index 46eab97d44f..9fd9da30f25 100644 --- a/packages/ai/src/tool.ts +++ b/packages/ai/src/tool.ts @@ -1,11 +1,12 @@ import { Effect, JsonSchema, Schema } from "effect" import { Tool } from "@opencode/schema/tool" import type { + Freeform, ToolCallPart, ToolDefinition as ToolDefinitionClass, ToolOutput as ToolOutputType, } from "./schema/index.js" -import { ToolDefinition, ToolFailure, ToolOutput } from "./schema/index.js" +import { ToolDefinition, ToolFailure, ToolOutput, type ToolDefinitionInput } from "./schema/index.js" import { isRecord } from "./utils/record.js" /** @@ -35,6 +36,23 @@ export type ToolToModelOutput, Success extend input: ToolModelOutputInput, Success["Encoded"]>, ) => ReadonlyArray +type FreeformField = { + [K in keyof T]-?: [Exclude] extends [never] + ? {} extends Pick + ? never + : T[K] extends string + ? K + : never + : never +}[keyof T] + +/** `Freeform` when the parameters are exactly one required string field, otherwise `undefined`. */ +export type FreeformOption> = [ + FreeformField>, +] extends [never] + ? undefined + : Freeform + /** * A type-safe LLM tool. Each tool bundles its own description, parameter * Schema and success Schema. The execute handler is optional: omit it when you @@ -87,6 +105,7 @@ type TypedToolConfig = { readonly description: string readonly parameters: ToolSchema readonly success: ToolSchema + readonly freeform?: Freeform readonly execute?: ToolExecute, ToolSchema> readonly toModelOutput?: ToolToModelOutput, ToolSchema> readonly toStructuredOutput?: (output: unknown) => unknown @@ -96,6 +115,7 @@ type DynamicToolConfig = { readonly description: string readonly jsonSchema: JsonSchema.JsonSchema readonly outputSchema?: JsonSchema.JsonSchema + readonly freeform?: Freeform readonly execute?: (params: unknown, context?: ToolExecuteContext) => Effect.Effect readonly toModelOutput?: (input: ToolModelOutputInput) => ReadonlyArray readonly toStructuredOutput?: (output: unknown) => unknown @@ -136,6 +156,7 @@ export function make, Success extends ToolSch readonly description: string readonly parameters: Parameters readonly success: Success + readonly freeform?: FreeformOption readonly execute: ToolExecute readonly toModelOutput?: ToolToModelOutput readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown @@ -144,6 +165,7 @@ export function make, Success extends ToolSch readonly description: string readonly parameters: Parameters readonly success: Success + readonly freeform?: FreeformOption readonly execute?: undefined readonly toModelOutput?: ToolToModelOutput readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown @@ -152,6 +174,7 @@ export function make(config: { readonly description: string readonly jsonSchema: JsonSchema.JsonSchema readonly outputSchema?: JsonSchema.JsonSchema + readonly freeform?: Freeform readonly execute: (params: unknown, context?: ToolExecuteContext) => Effect.Effect readonly toModelOutput?: (input: ToolModelOutputInput) => ReadonlyArray readonly toStructuredOutput?: (output: unknown) => unknown @@ -160,6 +183,7 @@ export function make(config: { readonly description: string readonly jsonSchema: JsonSchema.JsonSchema readonly outputSchema?: JsonSchema.JsonSchema + readonly freeform?: Freeform readonly execute?: undefined readonly toModelOutput?: (input: ToolModelOutputInput) => ReadonlyArray readonly toStructuredOutput?: (output: unknown) => unknown @@ -178,11 +202,12 @@ export function make(config: TypedToolConfig | DynamicToolConfig): AnyTool { _project: (parameters, id, output) => project(config.toModelOutput, config.toStructuredOutput, parameters, id, output), _legacyResult: config.toModelOutput === undefined && config.toStructuredOutput === undefined, - _definition: new ToolDefinition({ + _definition: definition({ name: "", description: config.description, inputSchema: config.jsonSchema, outputSchema: config.outputSchema, + freeform: config.freeform, }), } } @@ -198,11 +223,12 @@ export function make(config: TypedToolConfig | DynamicToolConfig): AnyTool { _project: (parameters, id, output) => project(config.toModelOutput, config.toStructuredOutput, parameters, id, output), _legacyResult: false, - _definition: new ToolDefinition({ + _definition: definition({ name: "", description: config.description, inputSchema: emptyInputJsonSchema(config.parameters) ?? toJsonSchema(config.parameters), outputSchema: toJsonSchema(config.success), + freeform: config.freeform, }), } } @@ -228,6 +254,7 @@ export const toDefinitions = (tools: Tools): ReadonlyArray description: item._definition.description, inputSchema: item._definition.inputSchema, outputSchema: item._definition.outputSchema, + freeform: item._definition.freeform, }), ) @@ -247,6 +274,12 @@ export const emptyInputJsonSchema = (schema: Schema.Top): JsonSchema.JsonSchema return { ...rest, type: "object", properties: {}, additionalProperties: false } } +const definition = (input: ToolDefinitionInput) => { + if (input.freeform !== undefined && ToolDefinition.freeformField(input.inputSchema) === undefined) + throw new Error("A freeform tool needs exactly one parameter, a required string") + return new ToolDefinition(input) +} + const annotationKeywords = new Set(["title", "description", "default", "examples", "readOnly", "writeOnly"]) const toJsonSchema = (schema: Schema.Top): JsonSchema.JsonSchema => { diff --git a/packages/ai/test/openai-freeform.test.ts b/packages/ai/test/openai-freeform.test.ts new file mode 100644 index 00000000000..e21d2569a07 --- /dev/null +++ b/packages/ai/test/openai-freeform.test.ts @@ -0,0 +1,76 @@ +import { describe, expect, test } from "bun:test" +import { LLMEvent, ToolDefinition } from "../src/effect.js" +import { OpenAIFreeform } from "../src/protocols/openai-freeform.js" +import { ToolStream } from "../src/protocols/utils/tool-stream.js" + +const inputSchema = { + type: "object", + properties: { code: { type: "string" } }, + required: ["code"], + additionalProperties: false, +} +const tool = (input: Partial = {}) => + ToolDefinition.make({ name: "run", description: "Run code", inputSchema, freeform: { type: "text" }, ...input }) +const custom = { field: "code", format: { type: "text" } } as const + +const RAW = ['say "hi"\n\tdone\\', "naïve 😀 \u2028", "\u0000 }{ ]"] + +describe("OpenAI freeform tools", () => { + test("resolves a freeform tool to its string field", () => { + expect(OpenAIFreeform.resolve(tool())).toEqual(custom) + expect(OpenAIFreeform.resolve(tool({ freeform: undefined }))).toBeUndefined() + expect(OpenAIFreeform.resolve(tool({ native: { openai: {} } }))).toBeUndefined() + expect( + OpenAIFreeform.resolve(tool({ inputSchema: { ...inputSchema, properties: { code: { type: "number" } } } })), + ).toBeUndefined() + expect(OpenAIFreeform.resolve(tool({ inputSchema: { ...inputSchema, required: [] } }))).toBeUndefined() + }) + + test("converts between raw text and the JSON input", () => { + for (const raw of RAW) { + const json = OpenAIFreeform.fromRaw(custom, raw) + expect(JSON.parse(json)).toEqual({ code: raw }) + expect(OpenAIFreeform.toRaw(custom, JSON.parse(json))).toBe(raw) + } + expect(OpenAIFreeform.fromRaw(undefined, "x")).toBe('{"input":"x"}') + expect(OpenAIFreeform.toRaw(custom, { code: 1 })).toBe('{"code":1}') + }) + + test("streams raw chunks as JSON fragments that add up to the input", () => { + for (const raw of RAW) { + // Split at every code unit, including inside surrogate pairs and escape-worthy characters. + const chunks = [...Array(raw.length).keys()].map((index) => raw[index]) + const fragments = [OpenAIFreeform.streamStart(custom), ...chunks.map(OpenAIFreeform.streamDelta)] + const started = ToolStream.start(ToolStream.empty(), "ctc_1", { + id: "call_1", + name: "run", + input: fragments.join(""), + }) + const closed = OpenAIFreeform.close(started, ["ctc_1"], { custom, raw }) + expect(closed.events).toMatchObject([{ type: "tool-input-delta", text: '"}' }]) + expect(JSON.parse(closed.tools.ctc_1?.input ?? "")).toEqual({ code: raw }) + } + }) + + test("leaves a call open when the final input disagrees with the streamed one", () => { + const tools = ToolStream.start(ToolStream.empty(), "ctc_1", { + id: "call_1", + name: "run", + input: OpenAIFreeform.streamStart(custom, "partial"), + }) + const closed = OpenAIFreeform.close(tools, ["ctc_1", "missing"], { custom, raw: "different" }) + expect(closed.events).toEqual([]) + expect(closed.tools).toBe(tools) + expect(OpenAIFreeform.close(tools, ["ctc_1"]).events.filter(LLMEvent.is.toolInputDelta)).toHaveLength(1) + }) + + test("keeps an item id only while the call type is unchanged", () => { + const customCall = { openai: OpenAIFreeform.metadata("ctc_1", true) } + const functionCall = { openai: OpenAIFreeform.metadata("fc_1", false) } + expect(OpenAIFreeform.keepsItemID(customCall, "openai", true)).toBe(true) + expect(OpenAIFreeform.keepsItemID(customCall, "openai", false)).toBe(false) + expect(OpenAIFreeform.keepsItemID(functionCall, "openai", false)).toBe(true) + expect(OpenAIFreeform.keepsItemID(functionCall, "openai", true)).toBe(false) + expect(OpenAIFreeform.keepsItemID(undefined, "openai", false)).toBe(true) + }) +}) diff --git a/packages/ai/test/provider/freeform-tools.test.ts b/packages/ai/test/provider/freeform-tools.test.ts new file mode 100644 index 00000000000..df18fce5b09 --- /dev/null +++ b/packages/ai/test/provider/freeform-tools.test.ts @@ -0,0 +1,312 @@ +import { describe, expect } from "bun:test" +import { Effect, Schema } from "effect" +import { + LLM, + LLMEvent, + Message, + ToolCallPart, + toDefinitions, + type Freeform, + type LanguageModel, +} from "../../src/effect.js" +import * as AmazonBedrockMantle from "../../src/providers/amazon-bedrock-mantle.js" +import * as Anthropic from "../../src/providers/anthropic.js" +import * as Azure from "../../src/providers/azure.js" +import * as OpenAI from "../../src/providers/openai.js" +import * as OpenAICompatible from "../../src/providers/openai-compatible.js" +import * as OpenAICompatibleResponses from "../../src/providers/openai-compatible-responses.js" +import * as OpenRouter from "../../src/providers/openrouter.js" +import * as VercelAIGateway from "../../src/providers/vercel-ai-gateway.js" +import { LLMClient } from "../../src/route.js" +import { compileRequest } from "../../src/route/client.js" +import { Tool } from "../../src/tool.js" +import { it } from "../lib/effect.js" +import { fixedResponse } from "../lib/http.js" +import { sseEvents } from "../lib/sse.js" + +const GRAMMAR = 'start: "ZZ" /[0-9]{3}/' + +const tools = (freeform?: Freeform) => + toDefinitions({ + run: Tool.make({ + description: "Run code", + parameters: Schema.Struct({ code: Schema.String }), + success: Schema.String, + freeform, + }), + }) + +const lark = tools({ type: "lark", grammar: GRAMMAR }) +// The same tool without `freeform`, as a caller declares it for a model without custom tools. +const plain = tools() + +const body = (model: LanguageModel, freeform = lark) => + compileRequest(LLM.request({ model, prompt: "Run it.", tools: freeform, toolChoice: "run" })).pipe( + Effect.map((prepared) => prepared.body), + ) + +const responses = OpenAI.model("gpt-5.4", { apiKey: "test" }) +const chat = OpenAI.chatModel("gpt-5.4", { apiKey: "test" }) + +const RESPONSES_LARK = { + type: "custom", + name: "run", + description: "Run code", + format: { type: "grammar", syntax: "lark", definition: GRAMMAR }, +} +const CHAT_LARK = { + type: "custom", + custom: { + name: "run", + description: "Run code", + format: { type: "grammar", grammar: { syntax: "lark", definition: GRAMMAR } }, + }, +} + +describe("freeform tools", () => { + it.effect("encodes each format as a Responses custom tool", () => + Effect.gen(function* () { + expect((yield* body(responses, tools({ type: "text" }))).tools).toEqual([ + { type: "custom", name: "run", description: "Run code", format: { type: "text" } }, + ]) + expect((yield* body(responses, tools({ type: "regex", pattern: "ZZ[0-9]{3}" }))).tools).toEqual([ + { + type: "custom", + name: "run", + description: "Run code", + format: { type: "grammar", syntax: "regex", definition: "ZZ[0-9]{3}" }, + }, + ]) + const prepared = yield* body(responses) + expect(prepared.tools).toEqual([RESPONSES_LARK]) + expect(prepared.tool_choice).toEqual({ type: "custom", name: "run" }) + }), + ) + + it.effect("encodes each format as a Chat custom tool", () => + Effect.gen(function* () { + expect((yield* body(chat, tools({ type: "text" }))).tools).toEqual([ + { type: "custom", custom: { name: "run", description: "Run code", format: { type: "text" } } }, + ]) + expect((yield* body(chat, tools({ type: "regex", pattern: "ZZ[0-9]{3}" }))).tools).toEqual([ + { + type: "custom", + custom: { + name: "run", + description: "Run code", + format: { type: "grammar", grammar: { syntax: "regex", definition: "ZZ[0-9]{3}" } }, + }, + }, + ]) + const prepared = yield* body(chat) + expect(prepared.tools).toEqual([CHAT_LARK]) + expect(prepared.tool_choice).toEqual({ type: "custom", custom: { name: "run" } }) + }), + ) + + it.effect("encodes custom tools in every route that reuses the OpenAI wire format", () => + Effect.gen(function* () { + const settings = { apiKey: "test" } + const responsesModels = [ + Azure.responsesModel("gpt-5.4", { ...settings, resourceName: "fixture" }), + AmazonBedrockMantle.responsesModel("openai.gpt-5.4", { ...settings, region: "us-east-1" }), + VercelAIGateway.responsesModel("openai/gpt-5.4", settings), + OpenAICompatibleResponses.model("gpt-5.4", { ...settings, baseURL: "https://responses.test/v1" }), + ] + const chatModels = [ + Azure.chatModel("gpt-5.4", { ...settings, resourceName: "fixture" }), + AmazonBedrockMantle.chatModel("openai.gpt-5.4", { ...settings, region: "us-east-1" }), + VercelAIGateway.chatModel("openai/gpt-5.4", settings), + OpenRouter.model("openai/gpt-5.4", settings), + OpenAICompatible.model("gpt-5.4", { ...settings, baseURL: "https://chat.test/v1" }), + ] + for (const model of responsesModels) { + const prepared = yield* body(model) + expect(prepared.tools).toEqual([RESPONSES_LARK]) + } + for (const model of chatModels) { + const prepared = yield* body(model) + expect(prepared.tools).toEqual([CHAT_LARK]) + } + }), + ) + + it.effect("sends JSON tools for tools without freeform and for other protocols", () => + Effect.gen(function* () { + const prepared = yield* body(responses, plain) + expect(prepared.tools).toMatchObject([{ type: "function", name: "run" }]) + expect(prepared.tool_choice).toEqual({ type: "function", name: "run" }) + expect((yield* body(chat, plain)).tools).toMatchObject([{ type: "function", function: { name: "run" } }]) + expect((yield* body(Anthropic.model("claude-sonnet-4-5", { apiKey: "test" }))).tools).toMatchObject([ + { name: "run", input_schema: { properties: { code: { type: "string" } } } }, + ]) + }), + ) + + it.effect("streams Responses custom calls as JSON argument deltas", () => + Effect.gen(function* () { + const item = { type: "custom_tool_call", id: "ctc_1", call_id: "call_1", name: "run", input: "" } + const response = yield* LLMClient.generate( + LLM.request({ model: responses, prompt: "Run it.", tools: lark }), + ).pipe( + Effect.provide( + fixedResponse( + sseEvents( + { type: "response.output_item.added", output_index: 0, item }, + { type: "response.custom_tool_call_input.delta", output_index: 0, item_id: "ctc_1", delta: "ZZ" }, + { type: "response.custom_tool_call_input.delta", output_index: 0, item_id: "ctc_1", delta: '"1\n' }, + { type: "response.custom_tool_call_input.done", output_index: 0, item_id: "ctc_1", input: 'ZZ"1\n' }, + { type: "response.output_item.done", output_index: 0, item: { ...item, input: 'ZZ"1\n' } }, + { type: "response.completed", response: { id: "resp_1" } }, + ), + ), + ), + ) + + const deltas = response.events.filter((event) => event.type === "tool-input-delta").map((event) => event.text) + expect(deltas).toEqual(['{"code":"', "ZZ", '\\"1\\n', '"}']) + expect(JSON.parse(deltas.join(""))).toEqual({ code: 'ZZ"1\n' }) + expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([ + expect.objectContaining({ + id: "call_1", + name: "run", + input: { code: 'ZZ"1\n' }, + providerMetadata: { openai: { itemId: "ctc_1", custom: true } }, + }), + ]) + expect(response.finishReason.normalized).toBe("tool-calls") + + const replay = yield* compileRequest(LLM.request({ model: responses, messages: [response.message], tools: lark })) + expect(replay.body.input[0]).toEqual({ + type: "custom_tool_call", + id: "ctc_1", + call_id: "call_1", + name: "run", + input: 'ZZ"1\n', + }) + }), + ) + + it.effect("parses a Responses custom call that arrives only when done", () => + Effect.gen(function* () { + const item = { type: "custom_tool_call", id: "ctc_1", call_id: "call_1", name: "run", input: "ZZ123" } + const response = yield* LLMClient.generate( + LLM.request({ model: responses, prompt: "Run it.", tools: lark }), + ).pipe( + Effect.provide( + fixedResponse( + sseEvents( + { type: "response.output_item.done", output_index: 0, item }, + { type: "response.completed", response: { id: "resp_1" } }, + ), + ), + ), + ) + expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([ + expect.objectContaining({ id: "call_1", name: "run", input: { code: "ZZ123" } }), + ]) + }), + ) + + it.effect("streams Chat custom calls as JSON argument deltas", () => + Effect.gen(function* () { + const chunk = (call: Record, finish: string | null = null) => ({ + id: "chatcmpl_1", + choices: [{ index: 0, delta: { tool_calls: [{ index: 0, ...call }] }, finish_reason: finish }], + }) + const response = yield* LLMClient.generate(LLM.request({ model: chat, prompt: "Run it.", tools: lark })).pipe( + Effect.provide( + fixedResponse( + sseEvents( + chunk({ id: "call_1", type: "custom", custom: { name: "run", input: "" } }), + chunk({ custom: { input: "ZZ" } }), + chunk({ custom: { input: '"1\n' } }), + { id: "chatcmpl_1", choices: [{ index: 0, delta: {}, finish_reason: "tool_calls" }] }, + ), + ), + ), + ) + + const deltas = response.events.filter((event) => event.type === "tool-input-delta").map((event) => event.text) + expect(deltas).toEqual(['{"code":"', "ZZ", '\\"1\\n', '"}']) + expect(response.events.filter(LLMEvent.is.toolCall)).toEqual([ + expect.objectContaining({ id: "call_1", name: "run", input: { code: 'ZZ"1\n' } }), + ]) + expect(response.finishReason.normalized).toBe("tool-calls") + }), + ) + + it.effect("replays history the way each tool is declared in the current request", () => + Effect.gen(function* () { + const history = (metadata: Record) => [ + Message.user("Run it."), + Message.assistant([ + ToolCallPart.make({ + id: "call_1", + name: "run", + input: { code: "ZZ123" }, + providerMetadata: { openai: metadata }, + }), + ]), + Message.tool({ id: "call_1", name: "run", result: "ok" }), + ] + const input = (declared: typeof lark, metadata: Record) => + compileRequest(LLM.request({ model: responses, messages: history(metadata), tools: declared })).pipe( + Effect.map((prepared) => prepared.body.input.slice(1)), + ) + const custom = { itemId: "ctc_1", custom: true } + + expect(yield* input(lark, custom)).toEqual([ + { type: "custom_tool_call", id: "ctc_1", call_id: "call_1", name: "run", input: "ZZ123" }, + { type: "custom_tool_call_output", call_id: "call_1", output: '"ok"' }, + ]) + expect(yield* input(plain, custom)).toEqual([ + { type: "function_call", call_id: "call_1", name: "run", arguments: '{"code":"ZZ123"}' }, + { type: "function_call_output", call_id: "call_1", output: '"ok"' }, + ]) + expect(yield* input(lark, { itemId: "fc_1" })).toEqual([ + { type: "custom_tool_call", call_id: "call_1", name: "run", input: "ZZ123" }, + { type: "custom_tool_call_output", call_id: "call_1", output: '"ok"' }, + ]) + expect(yield* input(plain, { itemId: "fc_1" })).toEqual([ + { type: "function_call", id: "fc_1", call_id: "call_1", name: "run", arguments: '{"code":"ZZ123"}' }, + { type: "function_call_output", call_id: "call_1", output: '"ok"' }, + ]) + + const messages = (model: LanguageModel, declared = lark) => + compileRequest(LLM.request({ model, messages: history(custom), tools: declared })).pipe( + Effect.map((prepared) => prepared.body.messages.slice(1)), + ) + expect(yield* messages(chat)).toMatchObject([ + { role: "assistant", tool_calls: [{ id: "call_1", type: "custom", custom: { name: "run", input: "ZZ123" } }] }, + { role: "tool", tool_call_id: "call_1", content: '"ok"' }, + ]) + expect(yield* messages(chat, plain)).toMatchObject([ + { + role: "assistant", + tool_calls: [{ id: "call_1", type: "function", function: { name: "run", arguments: '{"code":"ZZ123"}' } }], + }, + { role: "tool", tool_call_id: "call_1", content: '"ok"' }, + ]) + expect(yield* messages(Anthropic.model("claude-sonnet-4-5", { apiKey: "test" }))).toMatchObject([ + { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "run", input: { code: "ZZ123" } }] }, + { role: "user", content: [{ type: "tool_result", tool_use_id: "call_1" }] }, + ]) + }), + ) + + it.effect("rejects freeform tools without exactly one required string parameter", () => + Effect.sync(() => { + const make = (parameters: Schema.Struct) => + Tool.make({ + description: "Run code", + jsonSchema: Schema.toJsonSchemaDocument(parameters).schema, + freeform: { type: "text" }, + }) + expect(() => make(Schema.Struct({ code: Schema.Number }))).toThrow("exactly one parameter, a required string") + expect(() => make(Schema.Struct({ code: Schema.optional(Schema.String) }))).toThrow() + expect(() => make(Schema.Struct({ code: Schema.String, lang: Schema.String }))).toThrow() + expect(make(Schema.Struct({ code: Schema.String }))._definition.freeform).toEqual({ type: "text" }) + }), + ) +}) diff --git a/packages/ai/test/tool.types.ts b/packages/ai/test/tool.types.ts index e3feb55d381..bc5dcfd9c44 100644 --- a/packages/ai/test/tool.types.ts +++ b/packages/ai/test/tool.types.ts @@ -3,6 +3,7 @@ import { LLM, LLMRequest, ToolRuntime, toDefinitions } from "../src/effect.js" import * as OpenAIChat from "../src/protocols/openai-chat.js" import { Auth } from "../src/route.js" import { Tool } from "../src/tool.js" +import { AI } from "../src/index.js" const request = LLM.request({ model: OpenAIChat.route.with({ auth: Auth.bearer("fixture") }).model({ id: "gpt-4o-mini" }), @@ -38,3 +39,44 @@ ToolRuntime.dispatch({ executable }, { type: "tool-call", id: "call_1", name: "e // @ts-expect-error High-level tool orchestration overloads are intentionally not supported. LLM.stream({ request, tools: { schemaOnly } }) + +const code = Schema.Struct({ code: Schema.String }) + +Tool.make({ + description: "Run JavaScript.", + parameters: code, + success: Schema.String, + freeform: { type: "lark", grammar: 'start: "ZZ" /[0-9]{3}/' }, + execute: (input) => Effect.succeed(input.code), +}) + +AI.tool({ + description: "Run JavaScript.", + parameters: code, + freeform: { type: "regex", pattern: "ZZ[0-9]{3}" }, + execute: (input) => input.code, +}) + +Tool.make({ + description: "Run JavaScript.", + // @ts-expect-error A freeform tool's only parameter must be a string. + parameters: Schema.Struct({ code: Schema.Number }), + success: Schema.String, + freeform: { type: "text" }, +}) + +AI.tool({ + description: "Run JavaScript.", + parameters: Schema.Struct({ code: Schema.String, language: Schema.String }), + // @ts-expect-error A freeform tool takes exactly one parameter. + freeform: { type: "text" }, + execute: () => undefined, +}) + +AI.tool({ + description: "Run JavaScript.", + parameters: Schema.Struct({ code: Schema.optional(Schema.String) }), + // @ts-expect-error A freeform tool's parameter must be required. + freeform: { type: "text" }, + execute: () => undefined, +})