feat(ai): freeform tools (#59963)

This commit is contained in:
Aiden Cline
2026-10-28 13:21:11 -05:00
committed by GitHub
Unverified
parent 06d3c060a1
commit 45713a326c
15 changed files with 914 additions and 100 deletions
+21
View File
@@ -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
+1
View File
@@ -43,6 +43,7 @@ export {
EffortPart,
ContentPart,
Message,
Freeform,
ToolDefinition,
ToolNamespace,
ToolEntry,
+3 -1
View File
@@ -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 = <Parameters extends ToolSchema<any>>(config: {
readonly description: string
readonly parameters: Parameters
readonly freeform?: FreeformOption<Parameters>
readonly execute: (
params: Schema.Schema.Type<Parameters>,
context: Partial<ToolExecuteContext> & { readonly signal: AbortSignal },
@@ -255,6 +256,7 @@ export const tool = <Parameters extends ToolSchema<any>>(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,
+4 -2
View File
@@ -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<InputItem, { type: "function_call_output" }> =>
item.type === "function_call_output"
const isFunctionCallOutput = (
item: InputItem,
): item is Extract<InputItem, { type: "function_call_output" | "custom_tool_call_output" }> =>
item.type === "function_call_output" || item.type === "custom_tool_call_output"
const HOSTED_TOOLS = {
web_search_call: { name: "web_search", input: (item) => item.action ?? {} },
+130 -38
View File
@@ -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<typeof HostedTool>
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<string>
readonly custom: ReadonlyMap<string, OpenAIFreeform.Custom>
readonly hasFunctionCall: boolean
readonly lifecycle: Lifecycle.State
readonly outputItems: Readonly<Record<number, string>>
@@ -457,19 +482,45 @@ export const lowerTool = Effect.fnUntraced(function* (protocolName: string, tool
}
})
export const lowerTools = (tools: ReadonlyArray<ToolDefinition>, 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<ToolDefinition>,
adapter: ProviderAdapter,
custom: ReadonlyMap<string, OpenAIFreeform.Custom>,
) =>
Effect.forEach(
tools,
(tool): Effect.Effect<Schema.Schema.Type<typeof Tool> | HostedTool, AIError> =>
tool.native !== undefined && adapter.nativeTool ? adapter.nativeTool(tool.native) : lowerTool(adapter.name, tool),
(tool): Effect.Effect<Schema.Schema.Type<typeof Tool | typeof CustomTool> | 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<LLMRequest["toolChoice"]>) =>
export const namedTool = (name: string, custom: ReadonlyMap<string, OpenAIFreeform.Custom>) => ({
type: custom.has(name) ? ("custom" as const) : ("function" as const),
name,
})
export const lowerToolChoice = (
protocolName: string,
toolChoice: NonNullable<LLMRequest["toolChoice"]>,
custom: ReadonlyMap<string, OpenAIFreeform.Custom>,
) =>
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<string, OpenAIFreeform.Custom>,
) => {
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<Record<string, string>> = {
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<string>(),
custom: OpenAIFreeform.tools(request),
lifecycle: Lifecycle.initial(),
outputItems: {},
message: undefined,
+151 -46
View File
@@ -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<typeof OpenAIChatCacheControl>
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<typeof OpenAIChatTool>
// 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<typeof OpenAIChatAssistantToolCall>
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<typeof OpenAIChatToolCallDelta>
@@ -315,6 +349,9 @@ interface PendingToolDelta {
export interface ParserState {
readonly providerMetadataKey: string
readonly tools: ToolStream.State<number>
readonly custom: ReadonlyMap<string, OpenAIFreeform.Custom>
/** Stream indexes of custom tool calls, whose JSON fragment closes when the call finishes. */
readonly customCalls: ReadonlySet<number>
readonly pendingTools: Partial<Record<number, PendingToolDelta>>
readonly toolCallEvents: ReadonlyArray<LLMEvent>
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<string, OpenAIFreeform.Custom>
}
const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
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<LLMRequest["toolChoice"]>,
custom: ReadonlyMap<string, OpenAIFreeform.Custom>,
) =>
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<MessageLoweringOptions, "providerMetadataKey">,
) {
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<number>) {
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<number>(),
custom: OpenAIFreeform.tools(request),
customCalls: new Set<number>(),
pendingTools: {},
toolCallEvents: [],
lifecycle: Lifecycle.initial(),
@@ -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<string, Custom> =>
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 = <K extends string | number>(
tools: ToolStream.State<K>,
keys: Iterable<K>,
final?: { readonly custom: Custom | undefined; readonly raw: string },
) =>
[...keys].reduce<{ readonly tools: ToolStream.State<K>; readonly events: ReadonlyArray<LLMEvent> }>(
(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"
+20 -8
View File
@@ -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<string, OpenAIFreeform.Custom>) {
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<string, OpenAIFreeform.Custom>) {
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<LLMRequest["toolChoice"]>, tools: ReadonlyArray<ToolEntry>) =>
const lowerToolChoice = (
toolChoice: NonNullable<LLMRequest["toolChoice"]>,
tools: ReadonlyArray<ToolEntry>,
custom: ReadonlyMap<string, OpenAIFreeform.Custom>,
) =>
ProviderShared.matchToolChoice(NAME, toolChoice, {
auto: () => "auto" as const,
none: () => "none" as const,
@@ -216,7 +227,7 @@ const lowerToolChoice = (toolChoice: NonNullable<LLMRequest["toolChoice"]>, 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)),
}
})
+1 -1
View File
@@ -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],
+2 -1
View File
@@ -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"
+21
View File
@@ -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<typeof Freeform>
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 = {
+36 -3
View File
@@ -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<Parameters extends ToolSchema<any>, Success extend
input: ToolModelOutputInput<Schema.Schema.Type<Parameters>, Success["Encoded"]>,
) => ReadonlyArray<Tool.Content>
type FreeformField<T> = {
[K in keyof T]-?: [Exclude<keyof T, K>] extends [never]
? {} extends Pick<T, K>
? 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<Parameters extends ToolSchema<any>> = [
FreeformField<Schema.Schema.Type<Parameters>>,
] 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<any>
readonly success: ToolSchema<any>
readonly freeform?: Freeform
readonly execute?: ToolExecute<ToolSchema<any>, ToolSchema<any>>
readonly toModelOutput?: ToolToModelOutput<ToolSchema<any>, ToolSchema<any>>
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<unknown, ToolFailure>
readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>
readonly toStructuredOutput?: (output: unknown) => unknown
@@ -136,6 +156,7 @@ export function make<Parameters extends ToolSchema<any>, Success extends ToolSch
readonly description: string
readonly parameters: Parameters
readonly success: Success
readonly freeform?: FreeformOption<Parameters>
readonly execute: ToolExecute<Parameters, Success>
readonly toModelOutput?: ToolToModelOutput<Parameters, Success>
readonly toStructuredOutput?: (output: Success["Encoded"]) => unknown
@@ -144,6 +165,7 @@ export function make<Parameters extends ToolSchema<any>, Success extends ToolSch
readonly description: string
readonly parameters: Parameters
readonly success: Success
readonly freeform?: FreeformOption<Parameters>
readonly execute?: undefined
readonly toModelOutput?: ToolToModelOutput<Parameters, Success>
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<unknown, ToolFailure>
readonly toModelOutput?: (input: ToolModelOutputInput<unknown, unknown>) => ReadonlyArray<Tool.Content>
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<unknown, unknown>) => ReadonlyArray<Tool.Content>
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<ToolDefinitionClass>
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 => {
+76
View File
@@ -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.Input> = {}) =>
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<string>(), "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<string>(), "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)
})
})
@@ -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<string, unknown>, 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<string, unknown>) => [
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<string, unknown>) =>
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<Schema.Struct.Fields>) =>
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" })
}),
)
})
+42
View File
@@ -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,
})