mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-17 05:26:47 +03:00
feat(ai): freeform tools (#59963)
This commit is contained in:
committed by
GitHub
Unverified
parent
06d3c060a1
commit
45713a326c
@@ -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
|
||||
|
||||
@@ -43,6 +43,7 @@ export {
|
||||
EffortPart,
|
||||
ContentPart,
|
||||
Message,
|
||||
Freeform,
|
||||
ToolDefinition,
|
||||
ToolNamespace,
|
||||
ToolEntry,
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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 ?? {} },
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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"
|
||||
@@ -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)),
|
||||
}
|
||||
})
|
||||
|
||||
|
||||
@@ -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],
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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
@@ -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 => {
|
||||
|
||||
@@ -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" })
|
||||
}),
|
||||
)
|
||||
})
|
||||
@@ -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,
|
||||
})
|
||||
|
||||
Reference in New Issue
Block a user