diff --git a/packages/ai/README.md b/packages/ai/README.md index c0fe51c7808..ff1baed737c 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -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 }, diff --git a/packages/ai/example/tutorial.ts b/packages/ai/example/tutorial.ts index 3dcb380475e..145d264070b 100644 --- a/packages/ai/example/tutorial.ts +++ b/packages/ai/example/tutorial.ts @@ -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) { diff --git a/packages/ai/src/effect.ts b/packages/ai/src/effect.ts index 7bde72a2c3f..72d1a122c4a 100644 --- a/packages/ai/src/effect.ts +++ b/packages/ai/src/effect.ts @@ -197,7 +197,6 @@ export type { ToolExecuteContext, ToolModelOutputInput, ToolOptions, - Tools, ToolSchema, ToolToModelOutput, } from "./tool.js" diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts index 44aaed981fa..65e51b32295 100644 --- a/packages/ai/src/index.ts +++ b/packages/ai/src/index.ts @@ -128,7 +128,10 @@ export const make = (options: Options = {}) => { input: RequestInput | LLMRequest, options?: StreamOptions & RunOptions, ): Promise - function generate(input: ObjectInput | RequestInput | LLMRequest, options?: StreamOptions & RunOptions) { + function generate( + input: ObjectInput | RequestInput | LLMRequest, + options?: StreamOptions & RunOptions, + ) { return run(LLM.generate(input, options), options) } @@ -160,7 +163,10 @@ export const make = (options: Options = {}) => { request: CheckpointRequest, options: TriggerCompactOptions & RunOptions, ): Promise - function compact(request: CompactionRequest, options?: EndpointCompactOptions & RunOptions): Promise + function compact( + request: CompactionRequest, + options?: EndpointCompactOptions & RunOptions, + ): Promise // 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" diff --git a/packages/ai/src/llm.ts b/packages/ai/src/llm.ts index 23cf247aa16..718ea734d01 100644 --- a/packages/ai/src/llm.ts +++ b/packages/ai/src/llm.ts @@ -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 readonly prompt?: string | ContentPart | ReadonlyArray readonly messages?: ReadonlyArray - readonly tools?: ReadonlyArray + /** Sent in array order. Pass `tool(...)` values or wire entries such as hosted provider tools. */ + readonly tools?: ReadonlyArray readonly toolChoice?: ToolChoice.Input readonly generation?: GenerationOptions.Input readonly providerOptions?: NoInfer> @@ -113,7 +114,7 @@ export type LoopInput, "tools" > & { - readonly tools: Record + readonly tools: ReadonlyArray /** Called after each step that has tool calls; returning `true` ends the loop without running them. */ readonly until?: (state: { readonly steps: ReadonlyArray }) => 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 = ( ...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, diff --git a/packages/ai/src/tool-runtime.ts b/packages/ai/src/tool-runtime.ts index 44056b189d7..f356aaca74f 100644 --- a/packages/ai/src/tool-runtime.ts +++ b/packages/ai/src/tool-runtime.ts @@ -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 => { +export const dispatch = (tools: ReadonlyArray, call: ToolCallPart): Effect.Effect => { 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, { diff --git a/packages/ai/src/tool.ts b/packages/ai/src/tool.ts index 22e71ac65b3..33fb6efc2ae 100644 --- a/packages/ai/src/tool.ts +++ b/packages/ai/src/tool.ts @@ -67,6 +67,8 @@ export type FreeformOption> = * `ToolDefinition` so callers do not rebuild them per invocation. */ export interface Tool = any, Success extends ToolSchema = 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, Execute = ToolExecute, > = { + readonly name: string readonly description: string readonly freeform?: FreeformOption 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 - -/** - * 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 => - 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): ReadonlyArray => + tools.map((item) => item._definition) /** * Describes a no-argument Effect tool input as an empty object, or returns diff --git a/packages/ai/test/error-partial.test.ts b/packages/ai/test/error-partial.test.ts index 6fd695591a2..b006204722b 100644 --- a/packages/ai/test/error-partial.test.ts +++ b/packages/ai/test/error-partial.test.ts @@ -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([]) diff --git a/packages/ai/test/generate-object.test.ts b/packages/ai/test/generate-object.test.ts index c80cc83914a..ba53013f068 100644 --- a/packages/ai/test/generate-object.test.ts +++ b/packages/ai/test/generate-object.test.ts @@ -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) diff --git a/packages/ai/test/lib/tool-runtime.ts b/packages/ai/test/lib/tool-runtime.ts index ff82c8dfe9c..7697933aa1a 100644 --- a/packages/ai/test/lib/tool-runtime.ts +++ b/packages/ai/test/lib/tool-runtime.ts @@ -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 { +interface RunOptions { readonly request: LLMRequest - readonly tools: T + readonly tools: ReadonlyArray readonly maxSteps?: number } /** Test-owned continuation loop. Production callers must own durable history. */ -export const runTools = (options: RunOptions) => +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)], }) diff --git a/packages/ai/test/llm-option-types.types.ts b/packages/ai/test/llm-option-types.types.ts index af56a37c005..0a52494ab97 100644 --- a/packages/ai/test/llm-option-types.types.ts +++ b/packages/ai/test/llm-option-types.types.ts @@ -79,7 +79,7 @@ void ai.generate({ model, prompt: "Hello" }).pipe(Effect.map((response) => respo type FinishObject = Extract extends { readonly object?: infer O } ? O : never const streamedObject = ai.stream({ model, prompt: "Hello", schema: Schema.Struct({ answer: Schema.String }) }) type StreamObjectValue = Assert>, { 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, { readonly type: "finish" }>, diff --git a/packages/ai/test/loop-tools.types.ts b/packages/ai/test/loop-tools.types.ts index fee2cd0b84b..cb21e797c29 100644 --- a/packages/ai/test/loop-tools.types.ts +++ b/packages/ai/test/loop-tools.types.ts @@ -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(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(1), +}) +AI.ai.loop({ model, prompt: "Fail.", tools: [fail, parse, inspect] }) diff --git a/packages/ai/test/loop.test.ts b/packages/ai/test/loop.test.ts index 88c930ad9f1..d8c99b3974c 100644 --- a/packages/ai/test/loop.test.ts +++ b/packages/ai/test/loop.test.ts @@ -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) + }), + ) }) diff --git a/packages/ai/test/promise.test.ts b/packages/ai/test/promise.test.ts index 72a6493bd66..1bdb6f47a2f 100644 --- a/packages/ai/test/promise.test.ts +++ b/packages/ai/test/promise.test.ts @@ -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" }) diff --git a/packages/ai/test/provider/bedrock-converse.test.ts b/packages/ai/test/provider/bedrock-converse.test.ts index 8464b913793..38e90b0d114 100644 --- a/packages/ai/test/provider/bedrock-converse.test.ts +++ b/packages/ai/test/provider/bedrock-converse.test.ts @@ -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({ diff --git a/packages/ai/test/provider/freeform-tools.test.ts b/packages/ai/test/provider/freeform-tools.test.ts index 90b4cbbe71a..43a1c130d4f 100644 --- a/packages/ai/test/provider/freeform-tools.test.ts +++ b/packages/ai/test/provider/freeform-tools.test.ts @@ -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) => tool({ + name: "run", description: "Run code", jsonSchema: Schema.toJsonSchemaDocument(parameters).schema, freeform: { type: "text" }, diff --git a/packages/ai/test/provider/gemini-openai-chat.recorded.test.ts b/packages/ai/test/provider/gemini-openai-chat.recorded.test.ts index a38451260f9..0f90e1092b4 100644 --- a/packages/ai/test/provider/gemini-openai-chat.recorded.test.ts +++ b/packages/ai/test/provider/gemini-openai-chat.recorded.test.ts @@ -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) diff --git a/packages/ai/test/provider/openai-responses-websocket.recorded.test.ts b/packages/ai/test/provider/openai-responses-websocket.recorded.test.ts index fc1937346a3..51626eb5c76 100644 --- a/packages/ai/test/provider/openai-responses-websocket.recorded.test.ts +++ b/packages/ai/test/provider/openai-responses-websocket.recorded.test.ts @@ -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: [ diff --git a/packages/ai/test/provider/pdf.recorded.test.ts b/packages/ai/test/provider/pdf.recorded.test.ts index cece09c0867..2f797555d93 100644 --- a/packages/ai/test/provider/pdf.recorded.test.ts +++ b/packages/ai/test/provider/pdf.recorded.test.ts @@ -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" } }) diff --git a/packages/ai/test/provider/responses-routes.recorded.test.ts b/packages/ai/test/provider/responses-routes.recorded.test.ts index 7a142877f32..dd738974696 100644 --- a/packages/ai/test/provider/responses-routes.recorded.test.ts +++ b/packages/ai/test/provider/responses-routes.recorded.test.ts @@ -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 [ { diff --git a/packages/ai/test/recorded-scenarios.ts b/packages/ai/test/recorded-scenarios.ts index 2b0f8b851be..b1db8d8f60e 100644 --- a/packages/ai/test/recorded-scenarios.ts +++ b/packages/ai/test/recorded-scenarios.ts @@ -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[] = [] diff --git a/packages/ai/test/tool-runtime.test.ts b/packages/ai/test/tool-runtime.test.ts index 8a811ab0771..27b8269539b 100644 --- a/packages/ai/test/tool-runtime.test.ts +++ b/packages/ai/test/tool-runtime.test.ts @@ -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), ), diff --git a/packages/ai/test/tool-schema-projection.test.ts b/packages/ai/test/tool-schema-projection.test.ts index 30e842178e4..5f19cf9263b 100644 --- a/packages/ai/test/tool-schema-projection.test.ts +++ b/packages/ai/test/tool-schema-projection.test.ts @@ -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" } } }, diff --git a/packages/ai/test/tool.types.ts b/packages/ai/test/tool.types.ts index f9bb73d8ad1..325ba20a3e4 100644 --- a/packages/ai/test/tool.types.ts +++ b/packages/ai/test/tool.types.ts @@ -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 = 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 })