refactor(ai): tools are an array with names (#60811)

This commit is contained in:
Aiden Cline
2026-10-31 01:12:18 -05:00
committed by GitHub
Unverified
parent 6b08407a5a
commit 994ade5bf6
24 changed files with 273 additions and 178 deletions
+6 -3
View File
@@ -55,8 +55,9 @@ Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployme
`stream` runs one model call; `loop` runs the model's tool calls and calls the model again until it stops calling
tools. Events from every step arrive on one stream, with a `tool-result` after each tool runs. `until` is checked
after each step that has tool calls, with every step's `LLMResponse`; returning `true` ends the loop without running
them. `tool` takes a plain `async` execute; a throw or rejection goes back to the model as an error result, and
`signal` aborts when the loop is interrupted.
them. Tools are an array, sent in the order given so the provider can reuse its cached prompt prefix. Each tool has a
`name`, and two tools with the same name fail the request. `tool` takes a plain `async` execute; a throw or rejection
goes back to the model as an error result, and `signal` aborts when the loop is interrupted.
`tool` from `@opencode/ai/effect` takes the same options (including an optional `success` schema) with an Effect execute:
```ts
@@ -65,6 +66,7 @@ import { Schema } from "effect"
import { ai, tool } from "@opencode/ai"
const read_file = tool({
name: "read_file",
description: "Read a UTF-8 file.",
parameters: Schema.Struct({ path: Schema.String }),
execute: ({ path }, { signal }) => readFile(path, { encoding: "utf8", signal }),
@@ -73,7 +75,7 @@ const read_file = tool({
const events = ai.loop({
model,
prompt: "Summarize package.json.",
tools: { read_file },
tools: [read_file],
until: ({ steps }) => steps.length >= 8,
})
for await (const event of events) {
@@ -88,6 +90,7 @@ instead of JSON arguments: unconstrained `text`, or text matching a `regex` or `
```ts
const run_code = tool({
name: "run_code",
description: "Run JavaScript",
parameters: Schema.Struct({ code: Schema.String }),
freeform: { type: "lark", grammar: JS_GRAMMAR },
+6 -5
View File
@@ -2,7 +2,7 @@ import { Config, Effect, Formatter, Schema, Stream } from "effect"
import { HttpClientResponse } from "effect/http"
import { NodeFileSystem } from "@effect/platform-node"
import { ai, AIClient, LLMRequest, Media, Message, ProviderID, ToolRuntime } from "@opencode/ai/effect"
import { toDefinitions, tool } from "@opencode/ai/effect"
import { tool } from "@opencode/ai/effect"
import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor } from "@opencode/ai/route"
import { OpenAI } from "@opencode/ai/providers"
@@ -86,21 +86,22 @@ const streamText = ai.stream(request).pipe(
// 5. Tools are typed with Effect Schema. Provider turns remain explicit:
// advertise definitions on the request, stream one turn, dispatch local calls,
// then persist/build follow-up history in the enclosing product flow.
const tools = {
get_weather: tool({
const tools = [
tool({
name: "get_weather",
description: "Get current weather for a city.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.String }),
execute: (input) => Effect.succeed({ forecast: `${input.city}: sunny, 72F` }),
}),
}
]
const streamWithTools = Effect.gen(function* () {
const request = ai.request({
model,
prompt: "Use get_weather for San Francisco, then answer in one sentence.",
generation: { maxTokens: 80, temperature: 0 },
tools: toDefinitions(tools),
tools,
})
const events = Array.from(yield* ai.stream(request).pipe(Stream.runCollect))
for (const event of events) {
-1
View File
@@ -197,7 +197,6 @@ export type {
ToolExecuteContext,
ToolModelOutputInput,
ToolOptions,
Tools,
ToolSchema,
ToolToModelOutput,
} from "./tool.js"
+8 -3
View File
@@ -128,7 +128,10 @@ export const make = <R = never>(options: Options<R> = {}) => {
input: RequestInput<Model> | LLMRequest,
options?: StreamOptions & RunOptions,
): Promise<LLMResponse>
function generate(input: ObjectInput<OutputSchema> | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) {
function generate(
input: ObjectInput<OutputSchema> | RequestInput | LLMRequest,
options?: StreamOptions & RunOptions,
) {
return run(LLM.generate(input, options), options)
}
@@ -160,7 +163,10 @@ export const make = <R = never>(options: Options<R> = {}) => {
request: CheckpointRequest,
options: TriggerCompactOptions & RunOptions,
): Promise<CompactionCheckpointResponse>
function compact(request: CompactionRequest, options?: EndpointCompactOptions & RunOptions): Promise<CompactionResponse>
function compact(
request: CompactionRequest,
options?: EndpointCompactOptions & RunOptions,
): Promise<CompactionResponse>
// The overloads pair each request type with its mechanism; `LLM.compact` checks the route's capability at runtime.
function compact(
request: CheckpointRequest | CompactionRequest,
@@ -496,7 +502,6 @@ export type {
ToolExecuteContext,
ToolModelOutputInput,
ToolOptions,
Tools,
ToolSchema,
ToolToModelOutput,
} from "./tool.js"
+27 -22
View File
@@ -20,7 +20,7 @@ import {
type ToolEntryInput,
withPartial,
} from "./schema/index.js"
import { tool, toDefinitions, type ExecutableTool, type Tool, type ToolSchema } from "./tool.js"
import { tool, type ExecutableTool, type Tool, type ToolSchema } from "./tool.js"
import { ToolRuntime } from "./tool-runtime.js"
/** Input accepted by `LLM.request`, normalized into the canonical `LLMRequest` class. */
@@ -32,7 +32,8 @@ export type RequestInput<SelectedLanguageModel extends LanguageModel = LanguageM
readonly system?: string | SystemPart | ReadonlyArray<SystemPart>
readonly prompt?: string | ContentPart | ReadonlyArray<ContentPart>
readonly messages?: ReadonlyArray<Message | Message.Input>
readonly tools?: ReadonlyArray<ToolEntryInput>
/** Sent in array order. Pass `tool(...)` values or wire entries such as hosted provider tools. */
readonly tools?: ReadonlyArray<Tool | ToolEntryInput>
readonly toolChoice?: ToolChoice.Input
readonly generation?: GenerationOptions.Input
readonly providerOptions?: NoInfer<LanguageModelProviderOptions<SelectedLanguageModel>>
@@ -113,7 +114,7 @@ export type LoopInput<SelectedLanguageModel extends LanguageModel = LanguageMode
RequestInput<SelectedLanguageModel>,
"tools"
> & {
readonly tools: Record<string, ExecutableTool>
readonly tools: ReadonlyArray<ExecutableTool>
/** Called after each step that has tool calls; returning `true` ends the loop without running them. */
readonly until?: (state: { readonly steps: ReadonlyArray<LLMResponse> }) => boolean
}
@@ -192,11 +193,7 @@ export function loop(input: LoopInput & { readonly schema?: OutputSchema }, opti
),
)
})
return Stream.unwrap(
prepare({ ...rest, tools: toDefinitions(tools) }).pipe(
Effect.map(({ request, output }) => step(request, [], output)),
),
)
return Stream.unwrap(prepare({ ...rest, tools }).pipe(Effect.map(({ request, output }) => step(request, [], output))))
}
const OBJECT_TOOL = "generate_object"
@@ -208,20 +205,28 @@ const prepare = (input: Input) => {
if (input instanceof LLMRequest) return Effect.succeed({ request: input, output: undefined })
const { schema, ...rest } = input
return tryRequest(() => {
const base = request(rest)
if (schema === undefined) return { request: base, output: undefined }
const description = "Return the structured result by calling this tool."
const output: Tool = Schema.isSchema(schema)
? tool({ description, parameters: schema })
: tool({ description, jsonSchema: schema })
const toolChoice = base.tools.length === 0 ? ToolChoice.named(OBJECT_TOOL) : new ToolChoice({ type: "required" })
return {
output,
request: LLMRequest.update(base, {
tools: [...base.tools, ...toDefinitions({ [OBJECT_TOOL]: output })],
toolChoice,
}),
}
const output: Tool | undefined =
schema === undefined
? undefined
: Schema.isSchema(schema)
? tool({ name: OBJECT_TOOL, description, parameters: schema })
: tool({ name: OBJECT_TOOL, description, jsonSchema: schema })
const tools = rest.tools ?? []
const built = request(
output === undefined
? rest
: {
...rest,
tools: [...tools, output],
toolChoice: tools.length === 0 ? ToolChoice.named(OBJECT_TOOL) : new ToolChoice({ type: "required" }),
},
)
const duplicate = built.tools.find(
(entry, index) => built.tools.findIndex((other) => other.name === entry.name) !== index,
)
if (duplicate) throw new Error(`Duplicate tool name: ${duplicate.name}`)
return { request: built, output }
})
}
@@ -267,7 +272,7 @@ export const request = <const SelectedLanguageModel extends LanguageModel>(
...rest,
system: SystemPart.content(requestSystem),
messages: [...(messages?.map(Message.make) ?? []), ...(prompt === undefined ? [] : [Message.user(prompt)])],
tools: tools?.map(ToolEntry.make) ?? [],
tools: tools?.map((item) => ("_definition" in item ? item._definition : ToolEntry.make(item))) ?? [],
toolChoice: requestToolChoice ? ToolChoice.make(requestToolChoice) : undefined,
generation: requestGeneration === undefined ? undefined : GenerationOptions.make(requestGeneration),
providerOptions: requestProviderOptions,
+3 -3
View File
@@ -8,7 +8,7 @@ import {
type ToolOutput as ToolOutputType,
type ToolResultValue as ToolResultValueType,
} from "./schema/index.js"
import { type Tool, type Tools } from "./tool.js"
import { type Tool } from "./tool.js"
export interface ToolSettlement {
readonly result: ToolResultValueType
@@ -20,9 +20,9 @@ export interface DispatchResult extends ToolSettlement {
}
/** Execute one canonical tool call without owning provider IO or continuation. */
export const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<DispatchResult> => {
export const dispatch = (tools: ReadonlyArray<Tool>, call: ToolCallPart): Effect.Effect<DispatchResult> => {
const name = call.namespace === undefined ? call.name : `${call.namespace}.${call.name}`
const tool = tools[name]
const tool = tools.find((item) => item.name === name)
if (!tool)
return Effect.succeed(
result(call, {
+10 -26
View File
@@ -67,6 +67,8 @@ export type FreeformOption<Parameters extends ToolSchema<any>> =
* `ToolDefinition` so callers do not rebuild them per invocation.
*/
export interface Tool<Parameters extends ToolSchema<any> = any, Success extends ToolSchema<any> = any> {
/** The tool name the model sees and calls. */
readonly name: string
readonly description: string
readonly parameters: Parameters
readonly success: Success
@@ -105,6 +107,7 @@ export type ToolOptions<
Success extends ToolSchema<any>,
Execute = ToolExecute<Parameters, Success>,
> = {
readonly name: string
readonly description: string
readonly freeform?: FreeformOption<Parameters>
readonly execute?: Execute
@@ -120,6 +123,7 @@ export type ToolOptions<
*
* ```ts
* tool({
* name: "weather",
* description: "Get current weather",
* parameters: Schema.Struct({ city: Schema.String }),
* success: Schema.Struct({ temperature: Schema.Number }),
@@ -157,6 +161,7 @@ export function build(
execute: ((params: any, context?: ToolExecuteContext) => any) | undefined,
): Tool {
const shared = {
name: config.name,
description: config.description,
execute,
toModelOutput: config.toModelOutput,
@@ -173,7 +178,7 @@ export function build(
_encode: Effect.succeed,
_legacyResult: config.toModelOutput === undefined && config.toStructuredOutput === undefined,
_definition: definition({
name: "",
name: config.name,
description: config.description,
inputSchema: config.jsonSchema,
outputSchema: config.outputSchema,
@@ -188,7 +193,7 @@ export function build(
_encode: config.success ? Schema.encodeEffect(config.success) : (value) => Effect.succeed(value ?? null),
_legacyResult: false,
_definition: definition({
name: "",
name: config.name,
description: config.description,
inputSchema: emptyInputJsonSchema(config.parameters) ?? toJsonSchema(config.parameters),
outputSchema: config.success && toJsonSchema(config.success),
@@ -197,30 +202,9 @@ export function build(
}
}
/**
* A record of named tools. The record key becomes the tool name on the wire.
*/
export type Tools = Record<string, Tool>
/**
* Convert a tools record into the `ToolDefinition[]` shape that
* `LLMRequest.tools` expects.
*
* Tool names come from the record keys, so the per-tool cached
* `_definition` is rebuilt with the correct name here. The JSON Schema body
* is reused.
*/
export const toDefinitions = (tools: Tools): ReadonlyArray<ToolDefinitionClass> =>
Object.entries(tools).map(
([name, item]) =>
new ToolDefinition({
name,
description: item._definition.description,
inputSchema: item._definition.inputSchema,
outputSchema: item._definition.outputSchema,
freeform: item._definition.freeform,
}),
)
/** The `ToolDefinition[]` that `LLMRequest.tools` expects, in array order. */
export const toDefinitions = (tools: ReadonlyArray<Tool>): ReadonlyArray<ToolDefinitionClass> =>
tools.map((item) => item._definition)
/**
* Describes a no-argument Effect tool input as an empty object, or returns
+2 -1
View File
@@ -79,12 +79,13 @@ describe("AIError.partial", () => {
yield* client.push(textThenFail)
const echo = tool({
name: "echo",
description: "Echo a value.",
parameters: Schema.Struct({ value: Schema.String }),
success: Schema.String,
execute: ({ value }) => Effect.succeed(value),
})
const error = yield* ai.loop({ model, prompt: "Echo hi.", tools: { echo } }).pipe(Stream.runDrain, Effect.flip)
const error = yield* ai.loop({ model, prompt: "Echo hi.", tools: [echo] }).pipe(Stream.runDrain, Effect.flip)
expect(error.partial?.text).toBe("Partial answer")
expect(error.partial?.toolCalls).toEqual([])
+6 -3
View File
@@ -35,11 +35,12 @@ describe("tool (dynamic JSON Schema)", () => {
required: ["city"],
}
const lookup = tool({
name: "lookup",
description: "Look up something",
jsonSchema,
execute: () => Effect.succeed({ ok: true }),
})
const [definition] = toDefinitions({ lookup })
const [definition] = toDefinitions([lookup])
expect(definition?.name).toBe("lookup")
expect(definition?.description).toBe("Look up something")
expect(definition?.inputSchema).toEqual(jsonSchema)
@@ -49,6 +50,7 @@ describe("tool (dynamic JSON Schema)", () => {
Effect.gen(function* () {
const seen: unknown[] = []
const echo = tool({
name: "echo",
description: "echo",
jsonSchema: { type: "object" },
execute: (params) =>
@@ -199,6 +201,7 @@ describe("schema on ai.stream and ai.loop", () => {
const City = Schema.Struct({ city: Schema.String })
const scripted = testEffect(TestLLM.testLayer())
const echo = tool({
name: "echo",
description: "Echo a value.",
parameters: Schema.Struct({ value: Schema.String }),
execute: ({ value }) => Effect.succeed(value),
@@ -225,7 +228,7 @@ describe("schema on ai.stream and ai.loop", () => {
yield* client.push(TestLLM.toolCall("call-2", "generate_object", { city: "Paris" }))
const events = Array.from(
yield* ai.loop({ model, prompt: "Pick a city.", tools: { echo }, schema: City }).pipe(Stream.runCollect),
yield* ai.loop({ model, prompt: "Pick a city.", tools: [echo], schema: City }).pipe(Stream.runCollect),
)
expect(events.filter(LLMEvent.is.toolResult).map((event) => event.name)).toEqual(["echo"])
@@ -248,7 +251,7 @@ describe("schema on ai.stream and ai.loop", () => {
)
const events = Array.from(
yield* ai.loop({ model, prompt: "Pick a city.", tools: { echo }, schema: City }).pipe(Stream.runCollect),
yield* ai.loop({ model, prompt: "Pick a city.", tools: [echo], schema: City }).pipe(Stream.runCollect),
)
expect(events.some(LLMEvent.is.toolResult)).toBe(false)
+5 -5
View File
@@ -10,20 +10,20 @@ import {
ToolResultPart,
type Usage,
} from "../../src/schema/index.js"
import { type Tools, toDefinitions } from "../../src/tool.js"
import { type Tool, toDefinitions } from "../../src/tool.js"
import { ToolRuntime } from "../../src/tool-runtime.js"
interface RunOptions<T extends Tools> {
interface RunOptions {
readonly request: LLMRequest
readonly tools: T
readonly tools: ReadonlyArray<Tool>
readonly maxSteps?: number
}
/** Test-owned continuation loop. Production callers must own durable history. */
export const runTools = <T extends Tools>(options: RunOptions<T>) =>
export const runTools = (options: RunOptions) =>
Stream.unwrap(
Effect.gen(function* () {
const names = new Set(Object.keys(options.tools))
const names = new Set(options.tools.map((tool) => tool.name))
let request = LLMRequest.update(options.request, {
tools: [...options.request.tools.filter((tool) => !names.has(tool.name)), ...toDefinitions(options.tools)],
})
+1 -1
View File
@@ -79,7 +79,7 @@ void ai.generate({ model, prompt: "Hello" }).pipe(Effect.map((response) => respo
type FinishObject<T> = Extract<T, { readonly type: "finish" }> extends { readonly object?: infer O } ? O : never
const streamedObject = ai.stream({ model, prompt: "Hello", schema: Schema.Struct({ answer: Schema.String }) })
type StreamObjectValue = Assert<Equal<FinishObject<StreamEvent<typeof streamedObject>>, { readonly answer: string }>>
const loopedObject = ai.loop({ model, prompt: "Hello", tools: {}, schema: Schema.Struct({ answer: Schema.String }) })
const loopedObject = ai.loop({ model, prompt: "Hello", tools: [], schema: Schema.Struct({ answer: Schema.String }) })
type LoopObjectValue = Assert<
Equal<
Extract<StreamEvent<typeof loopedObject>, { readonly type: "finish" }>,
+26 -11
View File
@@ -7,18 +7,21 @@ import { AI } from "../src/index.js"
const model = OpenAIChat.route.with({ auth: Auth.bearer("fixture") }).model({ id: "gpt-4o-mini" })
const add = AI.tool({
name: "add",
description: "Add two numbers.",
parameters: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
execute: (input) => input.a + input.b,
})
const echo = AI.tool({
name: "echo",
description: "Echo text.",
parameters: Schema.String,
execute: (input) => input.toUpperCase(),
})
const weather = tool({
name: "weather",
description: "Get weather.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.String }),
@@ -26,6 +29,7 @@ const weather = tool({
})
const shout = tool({
name: "shout",
description: "Shout text.",
parameters: Schema.String,
success: Schema.String,
@@ -33,25 +37,36 @@ const shout = tool({
})
const schemaOnly = tool({
name: "schemaOnly",
description: "Get weather.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.String }),
})
AI.ai.loop({ model, prompt: "Add 2 and 3.", tools: { add } })
AI.ai.loop({ model, prompt: "Get weather.", tools: { weather } })
AI.ai.loop({ model, prompt: "Use any tool.", tools: { add, echo, weather, shout } })
ai.loop({ model, prompt: "Add 2 and 3.", tools: { add } })
ai.loop({ model, prompt: "Get weather.", tools: { weather } })
ai.loop({ model, prompt: "Use any tool.", tools: { add, echo, weather, shout } })
AI.ai.loop({ model, prompt: "Add 2 and 3.", tools: [add] })
AI.ai.loop({ model, prompt: "Get weather.", tools: [weather] })
AI.ai.loop({ model, prompt: "Use any tool.", tools: [add, echo, weather, shout] })
ai.loop({ model, prompt: "Add 2 and 3.", tools: [add] })
ai.loop({ model, prompt: "Get weather.", tools: [weather] })
ai.loop({ model, prompt: "Use any tool.", tools: [add, echo, weather, shout] })
// @ts-expect-error The loop runs tools, so each one needs an execute handler.
ai.loop({ model, prompt: "Get weather.", tools: { schemaOnly } })
ai.loop({ model, prompt: "Get weather.", tools: [schemaOnly] })
const unavailable = () => {
throw new Error("Unavailable.")
}
const fail = AI.tool({ description: "Fail.", parameters: Schema.String, execute: unavailable })
const parse = AI.tool({ description: "Parse.", parameters: Schema.String, execute: (text) => JSON.parse(text) })
const inspect = tool({ description: "Inspect.", parameters: Schema.String, execute: () => Effect.succeed<unknown>(1) })
AI.ai.loop({ model, prompt: "Fail.", tools: { fail, parse, inspect } })
const fail = AI.tool({ name: "fail", description: "Fail.", parameters: Schema.String, execute: unavailable })
const parse = AI.tool({
name: "parse",
description: "Parse.",
parameters: Schema.String,
execute: (text) => JSON.parse(text),
})
const inspect = tool({
name: "inspect",
description: "Inspect.",
parameters: Schema.String,
execute: () => Effect.succeed<unknown>(1),
})
AI.ai.loop({ model, prompt: "Fail.", tools: [fail, parse, inspect] })
+35 -2
View File
@@ -10,6 +10,7 @@ const model = LanguageModel.make({ id: "fictional-model", provider: "fixture", r
const it = testEffect(TestLLM.testLayer())
const read_file = tool({
name: "read_file",
description: "Read a file.",
parameters: Schema.Struct({ path: Schema.String }),
success: Schema.String,
@@ -18,7 +19,7 @@ const read_file = tool({
})
const collect = (until?: LLM.LoopInput["until"]) =>
ai.loop({ model, prompt: "Read the file.", tools: { read_file }, until }).pipe(
ai.loop({ model, prompt: "Read the file.", tools: [read_file], until }).pipe(
Stream.runCollect,
Effect.map((events) => Array.from(events)),
)
@@ -90,6 +91,7 @@ describe("ai.loop", () => {
TestLLM.text("Done.", "text-1"),
)
const add = AI.tool({
name: "add",
description: "Add two numbers.",
parameters: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
success: Schema.Number,
@@ -97,7 +99,7 @@ describe("ai.loop", () => {
toModelOutput: ({ output }) => [{ type: "text", text: `sum=${output}` }],
})
const events = yield* ai.loop({ model, prompt: "Add.", tools: { add } }).pipe(Stream.runCollect)
const events = yield* ai.loop({ model, prompt: "Add.", tools: [add] }).pipe(Stream.runCollect)
expect(Array.from(events).filter(LLMEvent.is.toolResult)).toEqual([
expect.objectContaining({ id: "call-1", result: { type: "text", value: "sum=5" } }),
@@ -142,4 +144,35 @@ describe("ai.loop", () => {
expect(events.at(-1)).toEqual(expect.objectContaining({ type: "provider-error", message: "Overloaded" }))
}),
)
it.effect("sends tools in array order, after wire entries given before them", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
yield* client.push(TestLLM.text("Done.", "text-1"))
const search = tool({ name: "search", description: "Search.", parameters: Schema.String })
yield* ai.generate({
model,
prompt: "Hi.",
tools: [{ name: "hosted", description: "Hosted.", inputSchema: {} }, read_file, search],
})
expect((yield* client.requests())[0].tools.map((tool) => tool.name)).toEqual(["hosted", "read_file", "search"])
}),
)
it.effect("fails the request when two tools share a name", () =>
Effect.gen(function* () {
const client = yield* TestLLM.Test
const copy = tool({ name: "read_file", description: "Read again.", parameters: Schema.String })
const loop = yield* ai
.loop({ model, prompt: "Hi.", tools: [read_file, read_file] })
.pipe(Stream.runDrain, Effect.flip)
const generate = yield* ai.generate({ model, prompt: "Hi.", tools: [read_file, copy] }).pipe(Effect.flip)
expect(loop.reason).toMatchObject({ _tag: "InvalidRequest", message: "Duplicate tool name: read_file" })
expect(generate.reason).toMatchObject({ _tag: "InvalidRequest", message: "Duplicate tool name: read_file" })
expect(yield* client.requests()).toHaveLength(0)
}),
)
})
+6 -11
View File
@@ -127,9 +127,7 @@ describe("AI promise client", () => {
const request = ai.request({ model: openai.chat("gpt-4o-mini"), prompt: "Say hello." })
const text = await ai.generate(request)
expect(text.text).toBe("Hello world")
expect((await ai.generate({ model: openai.chat("gpt-4o-mini"), prompt: "Say hello." })).text).toBe(
"Hello world",
)
expect((await ai.generate({ model: openai.chat("gpt-4o-mini"), prompt: "Say hello." })).text).toBe("Hello world")
const image = await ai.image.generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" })
expect(image.image).toBeInstanceOf(Media.Asset)
@@ -217,7 +215,7 @@ describe("AI promise client", () => {
expect((await ai.generate(request, options)).text).toBe("Hello world")
await Array.fromAsync(ai.stream(request, options))
await Array.fromAsync(ai.loop({ ...request, tools: {} }, options))
await Array.fromAsync(ai.loop({ ...request, tools: [] }, options))
expect(seen).toEqual(Array(3).fill("https://openai.test/v1/chat/completions"))
const responses = ai.request({ model: openai.responses("gpt-5"), prompt: "Hello" })
@@ -362,9 +360,7 @@ describe("AI promise client", () => {
const inFlight = new AbortController()
setTimeout(() => inFlight.abort(reason), 10)
expect(
await ai
.generate({ model: slow, prompt: "Hello" }, { signal: inFlight.signal })
.catch((error: unknown) => error),
await ai.generate({ model: slow, prompt: "Hello" }, { signal: inFlight.signal }).catch((error: unknown) => error),
).toBe(reason)
const preAborted = await Array.fromAsync(
@@ -447,6 +443,7 @@ describe("AI promise client", () => {
),
})
const read_file = AI.tool({
name: "read_file",
description: "Read a file.",
parameters: Schema.Struct({ path: Schema.String }),
execute: async ({ path }) => {
@@ -457,7 +454,7 @@ describe("AI promise client", () => {
})
const events = await Array.fromAsync(
ai.loop({ model: openai.chat("gpt-4o-mini"), prompt: "Read the files.", tools: { read_file } }),
ai.loop({ model: openai.chat("gpt-4o-mini"), prompt: "Read the files.", tools: [read_file] }),
)
expect(events.filter(LLMEvent.is.toolResult).map((event) => event.result)).toEqual([
@@ -532,9 +529,7 @@ describe("AI promise client", () => {
const request = ai.request({ model: openai.responses("gpt-5"), prompt: "Hello" })
const compacted = await ai.compact(request)
expect(compacted.replacement.flatMap((message) => message.content.map((part) => part.type))).toEqual([
"compaction",
])
expect(compacted.replacement.flatMap((message) => message.content.map((part) => part.type))).toEqual(["compaction"])
expect(compacted.usage?.totalTokens).toBe(110)
const triggered = await ai.compact(request, { mechanism: "trigger" })
@@ -1091,14 +1091,15 @@ describe("Bedrock Converse route", () => {
if (!call) throw new Error("Expected a tool call")
expect(call.name).toBe("browser.tabs.open")
const dispatched = yield* ToolRuntime.dispatch(
{
browser_tabs_open: tool({
[
tool({
name: "browser_tabs_open",
description: "Open a tab",
parameters: Schema.Struct({}),
success: Schema.String,
execute: () => Effect.die("A normalized replay name must not select an executor"),
}),
},
],
call,
)
expect(dispatched.result).toEqual({
@@ -29,14 +29,15 @@ import { sseEvents } from "../lib/sse.js"
const GRAMMAR = 'start: "ZZ" /[0-9]{3}/'
const tools = (freeform?: Freeform) =>
toDefinitions({
run: tool({
toDefinitions([
tool({
name: "run",
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.
@@ -300,6 +301,7 @@ describe("freeform tools", () => {
Effect.sync(() => {
const make = (parameters: Schema.Struct<Schema.Struct.Fields>) =>
tool({
name: "run",
description: "Run code",
jsonSchema: Schema.toJsonSchemaDocument(parameters).schema,
freeform: { type: "text" },
@@ -1,11 +1,11 @@
import { describe, expect } from "bun:test"
import { Effect } from "effect"
import { ai, LLMEvent, LLMRequest, Message, toDefinitions, ToolRuntime } from "../../src/effect.js"
import { ai, LLMEvent, LLMRequest, Message, ToolRuntime } from "../../src/effect.js"
import * as OpenAICompatible from "../../src/providers/openai-compatible.js"
import { LLMClient } from "../../src/route.js"
import { compileRequest } from "../../src/route/client.js"
import { recordedTests } from "../recorded-test.js"
import { weatherRuntimeTool, weatherToolName } from "../recorded-scenarios.js"
import { weatherRuntimeTool } from "../recorded-scenarios.js"
const model = OpenAICompatible.configure({
provider: "google",
@@ -28,12 +28,12 @@ describe("Gemini OpenAI-compatible Chat recorded", () => {
{ cassette: "openai-compatible-chat/gemini-parallel-tool-signatures" },
() =>
Effect.gen(function* () {
const tools = { [weatherToolName]: weatherRuntimeTool }
const tools = [weatherRuntimeTool]
const request = ai.request({
model,
system: "Call get_weather for every requested city in parallel, then answer in one short sentence.",
prompt: "What is the weather in Paris and in Tokyo?",
tools: toDefinitions(tools),
tools,
cache: "none",
})
const first = yield* LLMClient.generate(request)
@@ -13,7 +13,7 @@ import {
} from "../../src/route.js"
import { configure } from "../../src/providers/openai.js"
import { decodeJson } from "../../src/protocols/shared.js"
import { weatherRuntimeTool, weatherTool, weatherToolName } from "../recorded-scenarios.js"
import { weatherRuntimeTool, weatherTool } from "../recorded-scenarios.js"
import { recordedTests } from "../recorded-test.js"
const model = configure({ apiKey: process.env.OPENAI_API_KEY ?? "fixture" }).responses("gpt-5.5")
@@ -127,7 +127,7 @@ describe("OpenAI Responses WebSocket recorded", () => {
const first = yield* LLMClient.generate(request, { webSocket: channel.executor })
const call = first.toolCalls[0]
if (!call) yield* Effect.die("Expected get_weather tool call")
const result = yield* ToolRuntime.dispatch({ [weatherToolName]: weatherRuntimeTool }, call)
const result = yield* ToolRuntime.dispatch([weatherRuntimeTool], call)
const second = yield* LLMClient.generate(
LLMRequest.update(request, {
messages: [
@@ -90,6 +90,7 @@ const readPdf = ToolDefinition.make({
inputSchema: { type: "object", properties: {}, additionalProperties: false },
})
const readPdfRuntime = tool({
name: "read_pdf",
description: readPdf.description,
parameters: Schema.Struct({ path: Schema.String }),
success: Schema.String,
@@ -163,7 +164,7 @@ describe("PDF recorded", () => {
cache: "none",
generation: { maxTokens: target.maxTokens, temperature: 0 },
}),
tools: { read_pdf: readPdfRuntime },
tools: [readPdfRuntime],
}).pipe(Stream.runCollect),
)
expect(events.at(-1)).toMatchObject({ type: "finish", reason: { normalized: "stop" } })
@@ -7,14 +7,15 @@ import { tool } from "../../src/tool.js"
import { expectWeatherToolLoop, runWeatherToolLoop, weatherToolLoopRequest } from "../recorded-scenarios.js"
import { recordedTests } from "../recorded-test.js"
const run = toDefinitions({
run: tool({
const run = toDefinitions([
tool({
name: "run",
description: "Run a Python snippet.",
parameters: Schema.Struct({ code: Schema.String }),
success: Schema.String,
freeform: { type: "text" },
}),
})
])
for (const item of [
{
+2 -1
View File
@@ -45,6 +45,7 @@ export const weatherTool = ToolDefinition.make({
})
export const weatherRuntimeTool = tool({
name: weatherToolName,
description: weatherTool.description,
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
@@ -92,7 +93,7 @@ const restroomImage = () =>
export const runWeatherToolLoop = (request: LLMRequest) =>
Effect.gen(function* () {
const tools = { [weatherToolName]: weatherRuntimeTool }
const tools = [weatherRuntimeTool]
let next = LLMRequest.update(request, { tools: toDefinitions(tools) })
const events: LLMEvent[] = []
+49 -32
View File
@@ -40,6 +40,7 @@ const weatherFailureCause = new Error("weather lookup denied")
test("dispatches namespaced calls by qualified identity", async () => {
let context: ToolExecuteContext | undefined
const lookup = tool({
name: "crm.lookup",
description: "Look up a customer.",
parameters: Schema.Struct({}),
success: Schema.String,
@@ -50,7 +51,10 @@ test("dispatches namespaced calls by qualified identity", async () => {
})
const call = ToolCallPart.make({ id: "call_1", namespace: "crm", name: "lookup", input: {} })
const result = await Effect.runPromise(
ToolRuntime.dispatch({ "crm.lookup": lookup, lookup: schema_only_weather }, call),
ToolRuntime.dispatch(
[lookup, tool({ name: "lookup", description: "Unqualified lookup.", parameters: Schema.Struct({}) })],
call,
),
)
expect(result.result).toEqual({ type: "text", value: "customer" })
@@ -59,6 +63,7 @@ test("dispatches namespaced calls by qualified identity", async () => {
})
const get_weather = tool({
name: "get_weather",
description: "Get current weather for a city.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
@@ -71,6 +76,7 @@ const get_weather = tool({
})
const schema_only_weather = tool({
name: "get_weather",
description: "Get current weather for a city.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
@@ -84,7 +90,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -115,7 +121,7 @@ describe("LLMClient tools", () => {
generation: GenerationOptions.make({ maxTokens: 50 }),
toolChoice: ToolChoice.make("auto"),
}),
tools: { get_weather },
tools: [get_weather],
}).pipe(Stream.runCollect, Effect.provide(layer))
const second = bodies[1]
@@ -154,7 +160,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -176,6 +182,7 @@ describe("LLMClient tools", () => {
Effect.gen(function* () {
const calls: unknown[] = []
const projected = tool({
name: "projected",
description: "Project an encoded success.",
parameters: Schema.Struct({ prefix: Schema.String }),
success: Schema.Struct({ count: Schema.NumberFromString }),
@@ -187,7 +194,7 @@ describe("LLMClient tools", () => {
})
const dispatched = yield* ToolRuntime.dispatch(
{ projected },
[projected],
LLMEvent.toolCall({ id: "call_projected", name: "projected", input: { prefix: "count" } }),
)
@@ -208,6 +215,7 @@ describe("LLMClient tools", () => {
it.effect("preserves provider metadata on dispatched tool results", () =>
Effect.gen(function* () {
const text = tool({
name: "text",
description: "Return text.",
parameters: Schema.Struct({}),
success: Schema.String,
@@ -215,7 +223,7 @@ describe("LLMClient tools", () => {
})
const providerMetadata = { google: { thoughtSignature: "provider_sig" } }
const dispatched = yield* ToolRuntime.dispatch(
{ text },
[text],
LLMEvent.toolCall({ id: "call_1", name: "text", input: {}, providerMetadata }),
)
@@ -230,7 +238,7 @@ describe("LLMClient tools", () => {
])
const failed = yield* ToolRuntime.dispatch(
{},
[],
LLMEvent.toolCall({ id: "call_2", name: "missing", input: {}, providerMetadata }),
)
expect(failed.events).toEqual([
@@ -256,12 +264,14 @@ describe("LLMClient tools", () => {
it.effect("uses the narrow default projection for encoded typed success", () =>
Effect.gen(function* () {
const text = tool({
name: "text",
description: "Return text.",
parameters: Schema.Struct({}),
success: Schema.String,
execute: () => Effect.succeed("hello"),
})
const json = tool({
name: "json",
description: "Return JSON.",
parameters: Schema.Struct({}),
success: Schema.Struct({ ok: Schema.Boolean }),
@@ -269,10 +279,10 @@ describe("LLMClient tools", () => {
})
expect(
(yield* ToolRuntime.dispatch({ text }, LLMEvent.toolCall({ id: "call_text", name: "text", input: {} }))).output,
(yield* ToolRuntime.dispatch([text], LLMEvent.toolCall({ id: "call_text", name: "text", input: {} }))).output,
).toEqual({ structured: "hello", content: [{ type: "text", text: "hello" }] })
expect(
(yield* ToolRuntime.dispatch({ json }, LLMEvent.toolCall({ id: "call_json", name: "json", input: {} }))).output,
(yield* ToolRuntime.dispatch([json], LLMEvent.toolCall({ id: "call_json", name: "json", input: {} }))).output,
).toEqual({ structured: { ok: true }, content: [] })
}),
)
@@ -280,6 +290,7 @@ describe("LLMClient tools", () => {
it.effect("can retain model media while redacting duplicated structured payloads", () =>
Effect.gen(function* () {
const image = tool({
name: "image",
description: "Return an image.",
parameters: Schema.Struct({}),
success: Schema.Struct({ mime: Schema.String, data: Schema.String }),
@@ -291,7 +302,7 @@ describe("LLMClient tools", () => {
})
const dispatched = yield* ToolRuntime.dispatch(
{ image },
[image],
LLMEvent.toolCall({ id: "call_image", name: "image", input: {} }),
)
@@ -361,6 +372,7 @@ describe("LLMClient tools", () => {
it.effect("settles projected URL files as canonical tool results", () =>
Effect.gen(function* () {
const remote = tool({
name: "remote",
description: "Return a remote file.",
parameters: Schema.Struct({}),
success: Schema.Struct({ ok: Schema.Boolean }),
@@ -369,7 +381,7 @@ describe("LLMClient tools", () => {
})
const dispatched = yield* ToolRuntime.dispatch(
{ remote },
[remote],
LLMEvent.toolCall({ id: "call_remote", name: "remote", input: {} }),
)
@@ -386,11 +398,11 @@ describe("LLMClient tools", () => {
)
test("derives typed output schemas and preserves dynamic output schemas", () => {
const [typed] = toDefinitions({ get_weather })
const [typed] = toDefinitions([get_weather])
const schema = { type: "object", properties: { result: { type: "string" } } } as const
const [dynamic] = toDefinitions({
dynamic: tool({ description: "Dynamic tool.", jsonSchema: { type: "object" }, outputSchema: schema }),
})
const [dynamic] = toDefinitions([
tool({ name: "dynamic", description: "Dynamic tool.", jsonSchema: { type: "object" }, outputSchema: schema }),
])
expect(typed?.outputSchema).toMatchObject({
type: "object",
@@ -407,6 +419,7 @@ describe("LLMClient tools", () => {
it.effect("preserves content tool results from dynamic tools", () =>
Effect.gen(function* () {
const screenshot = tool({
name: "screenshot",
description: "Capture a screenshot.",
jsonSchema: { type: "object", properties: {} },
execute: () =>
@@ -420,7 +433,7 @@ describe("LLMClient tools", () => {
})
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { screenshot }, maxSteps: 1 }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [screenshot], maxSteps: 1 }).pipe(
Stream.runCollect,
Effect.provide(
scriptedResponses([sseEvents(toolCallChunk("call_1", "screenshot", "{}"), finishChunk("tool_calls"))]),
@@ -447,13 +460,14 @@ describe("LLMClient tools", () => {
Effect.gen(function* () {
const callerOwned = { type: "json" as const, value: { ok: true }, events: ["caller-owned"] }
const eventful = tool({
name: "eventful",
description: "Return an events field.",
jsonSchema: { type: "object", properties: {} },
execute: () => Effect.succeed(callerOwned),
})
const dispatched = yield* ToolRuntime.dispatch(
{ eventful },
[eventful],
LLMEvent.toolCall({ id: "call_1", name: "eventful", input: {} }),
)
@@ -473,13 +487,14 @@ describe("LLMClient tools", () => {
Effect.gen(function* () {
const malformed = { type: "content", value: [{ type: "text" }] }
const dynamic = tool({
name: "dynamic",
description: "Return caller-defined JSON.",
jsonSchema: { type: "object", properties: {} },
execute: () => Effect.succeed(malformed),
})
const dispatched = yield* ToolRuntime.dispatch(
{ dynamic },
[dynamic],
LLMEvent.toolCall({ id: "call_1", name: "dynamic", input: {} }),
)
@@ -504,7 +519,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather }, maxSteps: 1 }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather], maxSteps: 1 }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -519,6 +534,7 @@ describe("LLMClient tools", () => {
Effect.gen(function* () {
let context: ToolExecuteContext | undefined
const contextual = tool({
name: "contextual",
description: "Capture tool context.",
parameters: Schema.Struct({ value: Schema.String }),
success: Schema.Struct({ ok: Schema.Boolean }),
@@ -529,7 +545,7 @@ describe("LLMClient tools", () => {
}),
})
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { contextual } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [contextual] }).pipe(
Stream.runCollect,
Effect.provide(
scriptedResponses([
@@ -551,9 +567,10 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* LLMClient.stream(
LLMRequest.update(baseRequest, { tools: toDefinitions({ get_weather: schema_only_weather }) }),
).pipe(Stream.runCollect, Effect.provide(layer)),
yield* LLMClient.stream(LLMRequest.update(baseRequest, { tools: toDefinitions([schema_only_weather]) })).pipe(
Stream.runCollect,
Effect.provide(layer),
),
)
expect(events.find(LLMEvent.is.toolCall)).toMatchObject({ type: "tool-call", id: "call_1" })
@@ -608,7 +625,7 @@ describe("LLMClient tools", () => {
.with({ auth: Auth.header("x-api-key", "test") })
.model({ id: "claude-sonnet-4-5" }),
}),
tools: { get_weather },
tools: [get_weather],
}).pipe(Stream.runCollect, Effect.provide(layer))
expect(bodies[1]).toMatchObject({
@@ -686,7 +703,7 @@ describe("LLMClient tools", () => {
prompt: "Use the tool.",
providerOptions: { store: false, include: ["reasoning.encrypted_content"] },
}),
tools: { get_weather },
tools: [get_weather],
}).pipe(Stream.runCollect, Effect.provide(layer))
expect(bodies[1]).toMatchObject({
@@ -709,7 +726,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -740,7 +757,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -760,7 +777,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -780,7 +797,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -810,7 +827,7 @@ describe("LLMClient tools", () => {
const layer = scriptedResponses([toolCallStep, toolCallStep, toolCallStep])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather }, maxSteps: 2 }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather], maxSteps: 2 }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
@@ -869,7 +886,7 @@ describe("LLMClient tools", () => {
.with({ auth: Auth.header("x-api-key", "test") })
.model({ id: "claude-sonnet-4-5" }),
}),
tools: {},
tools: [],
}).pipe(Stream.runCollect, Effect.provide(layer)),
)
@@ -905,7 +922,7 @@ describe("LLMClient tools", () => {
])
const events = Array.from(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
yield* TestToolRuntime.runTools({ request: baseRequest, tools: [get_weather] }).pipe(
Stream.runCollect,
Effect.provide(layer),
),
+38 -27
View File
@@ -32,15 +32,16 @@ const reversed = Token.pipe(
describe("tool schema projections", () => {
test("only normalizes typed empty input structs, preserving raw schemas and output schemas", () => {
const schema = { not: { type: "null" } }
const definitions = toDefinitions({
typed: tool({
const definitions = toDefinitions([
tool({
name: "typed",
description: "Typed",
parameters: Schema.Struct({}),
success: Schema.Struct({}),
execute: () => Effect.succeed({}),
}),
raw: tool({ description: "Raw", jsonSchema: schema, execute: () => Effect.succeed({}) }),
})
tool({ name: "raw", description: "Raw", jsonSchema: schema, execute: () => Effect.succeed({}) }),
])
expect(definitions[0]?.inputSchema).toEqual({ type: "object", properties: {}, additionalProperties: false })
expect(definitions[0]?.outputSchema).toEqual(schema)
expect(definitions[1]?.inputSchema).toEqual(schema)
@@ -49,10 +50,10 @@ describe("tool schema projections", () => {
test("retains empty input descriptions and preserves named outputs and explicit raw schemas", () => {
const parameters = Schema.Struct({}).annotate({ identifier: "Ping", description: "No arguments" })
const raw = { $ref: "#/$defs/Raw", $defs: { Raw: { not: { type: "null" }, description: "Raw schema" } } }
const definitions = toDefinitions({
typed: tool({ description: "Ping", parameters, success: parameters, execute: () => Effect.succeed({}) }),
raw: tool({ description: "Raw", jsonSchema: raw, execute: () => Effect.succeed({}) }),
})
const definitions = toDefinitions([
tool({ name: "typed", description: "Ping", parameters, success: parameters, execute: () => Effect.succeed({}) }),
tool({ name: "raw", description: "Raw", jsonSchema: raw, execute: () => Effect.succeed({}) }),
])
expect(definitions[0]?.inputSchema).toEqual({
type: "object",
properties: {},
@@ -67,38 +68,43 @@ describe("tool schema projections", () => {
})
test("normalizes inputs whose encoded side is an empty struct", () => {
const definitions = toDefinitions({
defaulted: tool({ description: "Defaulted", parameters: defaulted, success: defaulted }),
named: tool({
const definitions = toDefinitions([
tool({ name: "defaulted", description: "Defaulted", parameters: defaulted, success: defaulted }),
tool({
name: "named",
description: "Named",
parameters: defaulted.annotate({ identifier: "Defaulted" }),
success: Schema.String,
}),
encodedMetadata: tool({
tool({
name: "encodedMetadata",
description: "Encoded metadata",
parameters: Schema.Struct({})
.annotate({ identifier: "Ping", title: "Ping", description: "No arguments" })
.pipe(Schema.decodeTo(Token, fromEmpty)),
success: Schema.String,
}),
decodedCheck: tool({
tool({
name: "decodedCheck",
description: "Decoded check",
parameters: defaulted.check(Schema.makeFilter(() => true, { toJsonSchema: () => ({ minProperties: 1 }) })),
success: Schema.String,
}),
reversed: tool({ description: "Reversed", parameters: reversed, success: Schema.String }),
encodedCheck: tool({
tool({ name: "reversed", description: "Reversed", parameters: reversed, success: Schema.String }),
tool({
name: "encodedCheck",
description: "Encoded check",
parameters: Schema.Struct({}).check(Schema.isMinProperties(1)),
success: Schema.String,
}),
// A filter without a JSON Schema form emits nothing, so the input still describes an empty object.
encodedFilter: tool({
tool({
name: "encodedFilter",
description: "Encoded filter",
parameters: Schema.Struct({}).check(Schema.makeFilter(() => true)),
success: Schema.String,
}),
})
])
expect(definitions[0]?.inputSchema).toEqual(empty)
expect(definitions[0]?.outputSchema).toEqual({ not: { type: "null" } })
expect(definitions[1]?.inputSchema).toEqual(empty)
@@ -161,33 +167,37 @@ describe("tool schema projections", () => {
ai.request({
model: scenario.route.with({ auth: Auth.bearer("test") }).model({ id: "test-model" }),
prompt: "Use a tool.",
tools: toDefinitions({
ping: tool({
tools: [
tool({
name: "ping",
description: "Ping",
parameters: Schema.Struct({}),
success: Schema.String,
execute: () => Effect.succeed("pong"),
}),
lookup: tool({
tool({
name: "lookup",
description: "Lookup",
parameters: Schema.Struct({ query: Schema.String }),
success: Schema.String,
execute: (input) => Effect.succeed(input.query),
}),
raw: tool({ description: "Raw", jsonSchema: raw, execute: () => Effect.succeed("raw") }),
reversed: tool({
tool({ name: "raw", description: "Raw", jsonSchema: raw, execute: () => Effect.succeed("raw") }),
tool({
name: "reversed",
description: "Reversed",
parameters: reversed,
success: Schema.String,
execute: () => Effect.succeed("reversed"),
}),
checked: tool({
tool({
name: "checked",
description: "Checked",
parameters: Schema.Struct({}).check(Schema.isMinProperties(1)),
success: Schema.String,
execute: () => Effect.succeed("checked"),
}),
}),
],
}),
)
expect(prepared.body.tools).toMatchObject(scenario.tools)
@@ -288,13 +298,14 @@ describe("tool schema projections", () => {
tools: [{ name: "lookup", description: "Lookup data.", inputSchema }],
}),
).pipe(Effect.map((prepared) => prepared.body.tools?.[0]?.function.parameters))
const parameterless = toDefinitions({
lookup: tool({
const parameterless = toDefinitions([
tool({
name: "lookup",
description: "Lookup data.",
parameters: Schema.Struct({}).annotate({ description: "No input." }),
success: Schema.String,
}),
})[0].inputSchema
])[0].inputSchema
const union = {
anyOf: [
{ type: "object", properties: { a: { type: "string" } } },
+22 -5
View File
@@ -10,6 +10,7 @@ const request = ai.request({
})
const executable = tool({
name: "executable",
description: "Get weather.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.String }),
@@ -17,12 +18,14 @@ const executable = tool({
})
const schemaOnly = tool({
name: "schemaOnly",
description: "Get weather.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.String }),
})
tool({
name: "forecast",
description: "Encode success before projection.",
parameters: Schema.Struct({ city: Schema.String }),
success: Schema.Struct({ forecast: Schema.NumberFromString }),
@@ -33,15 +36,24 @@ tool({
})
ai.stream(request)
ai.generate(LLMRequest.update(request, { tools: toDefinitions({ schemaOnly }) }))
ToolRuntime.dispatch({ executable }, { type: "tool-call", id: "call_1", name: "executable", input: { city: "Paris" } })
ai.generate(LLMRequest.update(request, { tools: toDefinitions([schemaOnly]) }))
ToolRuntime.dispatch([executable], { type: "tool-call", id: "call_1", name: "executable", input: { city: "Paris" } })
// @ts-expect-error High-level tool orchestration overloads are intentionally not supported.
ai.stream({ request, tools: { schemaOnly } })
ai.stream({ model: request.model, prompt: "Use the tool.", tools: [schemaOnly, executable] })
ai.generate({
model: request.model,
prompt: "Use the tool.",
tools: [schemaOnly, { name: "raw", description: "Raw.", inputSchema: {} }],
})
// @ts-expect-error A tool needs a name.
tool({ description: "Unnamed.", parameters: Schema.String })
// @ts-expect-error Tools are an array, not a record.
ai.loop({ model: request.model, prompt: "Use the tool.", tools: { executable } })
const code = Schema.Struct({ code: Schema.String })
tool({
name: "run_code",
description: "Run JavaScript.",
parameters: code,
success: Schema.String,
@@ -50,6 +62,7 @@ tool({
})
AI.tool({
name: "run_code",
description: "Run JavaScript.",
parameters: code,
freeform: { type: "regex", pattern: "ZZ[0-9]{3}" },
@@ -57,6 +70,7 @@ AI.tool({
})
tool({
name: "run_code",
description: "Run JavaScript.",
parameters: Schema.Struct({ code: Schema.Number }),
success: Schema.String,
@@ -65,6 +79,7 @@ tool({
})
AI.tool({
name: "run_code",
description: "Run JavaScript.",
parameters: Schema.Struct({ code: Schema.String, language: Schema.String }),
// @ts-expect-error A freeform tool takes exactly one parameter.
@@ -73,6 +88,7 @@ AI.tool({
})
AI.tool({
name: "run_code",
description: "Run JavaScript.",
parameters: Schema.Struct({ code: Schema.optional(Schema.String) }),
// @ts-expect-error A freeform tool's parameter must be required.
@@ -81,6 +97,7 @@ AI.tool({
})
const sum = {
name: "sum",
description: "Add two numbers.",
parameters: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
success: Schema.Number,
@@ -89,7 +106,7 @@ const sum = {
const declared: AI.Tool<typeof sum.parameters, typeof Schema.Number> = AI.tool(sum)
const effectSum: ExecutableTool = tool({ ...sum, execute: ({ a, b }) => Effect.succeed(a + b) })
const promiseSum: AI.ExecutableTool = AI.tool({ ...sum, execute: async ({ a, b }) => a + b })
toDefinitions({ declared, effectSum, promiseSum, dynamic: AI.tool({ description: "Look up.", jsonSchema: {} }) })
toDefinitions([declared, effectSum, promiseSum, AI.tool({ name: "dynamic", description: "Look up.", jsonSchema: {} })])
// @ts-expect-error The Effect tool's execute returns an Effect.
tool({ ...sum, execute: ({ a, b }) => a + b })