mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 08:39:02 +03:00
refactor(ai): tools are an array with names (#60811)
This commit is contained in:
committed by
GitHub
Unverified
parent
6b08407a5a
commit
994ade5bf6
@@ -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 },
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -197,7 +197,6 @@ export type {
|
||||
ToolExecuteContext,
|
||||
ToolModelOutputInput,
|
||||
ToolOptions,
|
||||
Tools,
|
||||
ToolSchema,
|
||||
ToolToModelOutput,
|
||||
} from "./tool.js"
|
||||
|
||||
@@ -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
@@ -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,
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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([])
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)],
|
||||
})
|
||||
|
||||
@@ -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" }>,
|
||||
|
||||
@@ -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] })
|
||||
|
||||
@@ -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)
|
||||
}),
|
||||
)
|
||||
})
|
||||
|
||||
@@ -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 [
|
||||
{
|
||||
|
||||
@@ -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[] = []
|
||||
|
||||
|
||||
@@ -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),
|
||||
),
|
||||
|
||||
@@ -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" } } },
|
||||
|
||||
@@ -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 })
|
||||
|
||||
Reference in New Issue
Block a user