@copilotkitnext/agent 1.53.1-next.2 → 1.54.0-next.3

package/src/__tests__/standard-schema-types.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expectTypeOf } from "vitest";
+import { z } from "zod";
+import * as v from "valibot";
+import { type } from "arktype";
+import type { StandardSchemaV1 } from "@copilotkitnext/shared";
+import { defineTool, type ToolDefinition } from "../index";
+
+describe("ToolDefinition type inference", () => {
+  describe("defineTool with Zod", () => {
+    it("infers execute args from Zod schema", () => {
+      const tool = defineTool({
+        name: "weather",
+        description: "Get weather",
+        parameters: z.object({
+          city: z.string(),
+          units: z.enum(["celsius", "fahrenheit"]),
+        }),
+        execute: async (args) => {
+          // args should be fully typed
+          expectTypeOf(args).toEqualTypeOf<{
+            city: string;
+            units: "celsius" | "fahrenheit";
+          }>();
+          return {};
+        },
+      });
+
+      expectTypeOf(tool.name).toBeString();
+      expectTypeOf(tool.description).toBeString();
+      expectTypeOf(tool.parameters).toMatchTypeOf<StandardSchemaV1>();
+    });
+
+    it("infers execute args with optional Zod fields", () => {
+      defineTool({
+        name: "search",
+        description: "Search",
+        parameters: z.object({
+          query: z.string(),
+          limit: z.number().optional(),
+        }),
+        execute: async (args) => {
+          expectTypeOf(args).toEqualTypeOf<{
+            query: string;
+            limit?: number | undefined;
+          }>();
+          return {};
+        },
+      });
+    });
+  });
+
+  describe("defineTool with Valibot", () => {
+    it("infers execute args from Valibot schema", () => {
+      defineTool({
+        name: "search",
+        description: "Search",
+        parameters: v.object({
+          query: v.string(),
+          limit: v.number(),
+        }),
+        execute: async (args) => {
+          expectTypeOf(args).toEqualTypeOf<{
+            query: string;
+            limit: number;
+          }>();
+          return {};
+        },
+      });
+    });
+
+    it("infers execute args with optional Valibot fields", () => {
+      defineTool({
+        name: "search",
+        description: "Search",
+        parameters: v.object({
+          query: v.string(),
+          limit: v.optional(v.number()),
+        }),
+        execute: async (args) => {
+          expectTypeOf(args).toEqualTypeOf<{
+            query: string;
+            limit?: number | undefined;
+          }>();
+          return {};
+        },
+      });
+    });
+  });
+
+  describe("defineTool with ArkType", () => {
+    it("infers execute args from ArkType schema", () => {
+      defineTool({
+        name: "search",
+        description: "Search",
+        parameters: type({
+          query: "string",
+          limit: "number",
+        }),
+        execute: async (args) => {
+          expectTypeOf(args).toEqualTypeOf<{
+            query: string;
+            limit: number;
+          }>();
+          return {};
+        },
+      });
+    });
+
+    it("infers execute args with optional ArkType fields", () => {
+      defineTool({
+        name: "profile",
+        description: "Profile",
+        parameters: type({
+          name: "string",
+          "age?": "number",
+        }),
+        execute: async (args) => {
+          expectTypeOf(args).toEqualTypeOf<{
+            name: string;
+            age?: number;
+          }>();
+          return {};
+        },
+      });
+    });
+  });
+
+  describe("ToolDefinition interface", () => {
+    it("accepts Zod schema as generic parameter", () => {
+      type ZodTool = ToolDefinition<z.ZodObject<{ city: z.ZodString }>>;
+
+      expectTypeOf<ZodTool["execute"]>().toBeFunction();
+      expectTypeOf<Parameters<ZodTool["execute"]>[0]>().toEqualTypeOf<{
+        city: string;
+      }>();
+    });
+
+    it("default generic parameter is StandardSchemaV1", () => {
+      type DefaultTool = ToolDefinition;
+
+      expectTypeOf<
+        DefaultTool["parameters"]
+      >().toMatchTypeOf<StandardSchemaV1>();
+    });
+
+    it("preserves schema type through defineTool return", () => {
+      const schema = z.object({ x: z.number() });
+      const tool = defineTool({
+        name: "t",
+        description: "d",
+        parameters: schema,
+        execute: async () => ({}),
+      });
+
+      expectTypeOf(tool.parameters).toEqualTypeOf<typeof schema>();
+    });
+  });
+});

package/src/__tests__/utils.test.ts

@@ -421,6 +421,84 @@ describe("convertToolDefinitionsToVercelAITools", () => {
   });
 });
 
+describe("ensureObjectArgs via convertMessagesToVercelAISDKMessages", () => {
+  function makeAssistantWithToolArgs(argsJson: string): Message[] {
+    return [
+      {
+        id: "1",
+        role: "assistant",
+        content: "calling tool",
+        toolCalls: [
+          {
+            id: "call1",
+            type: "function",
+            function: {
+              name: "myTool",
+              arguments: argsJson,
+            },
+          },
+        ],
+      },
+    ];
+  }
+
+  it("should pass through valid object arguments", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs('{"key":"value"}'),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({ key: "value" });
+  });
+
+  it("should replace a string argument with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs('""'),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+
+  it("should replace an array argument with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs("[1,2,3]"),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+
+  it("should replace a null argument with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs("null"),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+
+  it("should replace a numeric argument with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs("42"),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+
+  it("should replace a boolean argument with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs("true"),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+
+  it("should replace unparseable JSON with an empty object", () => {
+    const result = convertMessagesToVercelAISDKMessages(
+      makeAssistantWithToolArgs("{broken"),
+    );
+    const toolCall = (result[0] as any).content[1];
+    expect(toolCall.input).toEqual({});
+  });
+});
+
 describe("defineTool", () => {
   it("should create a ToolDefinition", () => {
     const tool = defineTool({

package/src/__tests__/zod-regression.test.ts

@@ -0,0 +1,350 @@
+/**
+ * Regression tests proving that the agent package's defineTool and
+ * convertToolDefinitionsToVercelAITools still work identically with
+ * Zod schemas after the Standard Schema migration.
+ *
+ * Covers:
+ * 1. defineTool with complex Zod schemas
+ * 2. convertToolDefinitionsToVercelAITools passes Zod schemas directly
+ *    (not through JSON Schema conversion — critical behavioral regression)
+ * 3. BuiltInAgent with Zod tools still works end-to-end
+ * 4. execute callback receives correctly shaped args
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { z } from "zod";
+import {
+  defineTool,
+  convertToolDefinitionsToVercelAITools,
+  BuiltInAgent,
+} from "../index";
+import type { RunAgentInput } from "@ag-ui/client";
+import { streamText } from "ai";
+import { mockStreamTextResponse, finish, collectEvents } from "./test-helpers";
+
+vi.mock("ai", async () => {
+  const actual = await vi.importActual("ai");
+  return {
+    ...actual,
+    streamText: vi.fn(),
+    tool: vi.fn((config) => config),
+    stepCountIs: vi.fn((count: number) => ({ type: "stepCount", count })),
+  };
+});
+
+vi.mock("@ai-sdk/openai", () => ({
+  createOpenAI: vi.fn(() => (modelId: string) => ({
+    modelId,
+    provider: "openai",
+  })),
+}));
+
+describe("defineTool Zod regression", () => {
+  it("complex Zod schema with nested objects, arrays, unions", () => {
+    const tool = defineTool({
+      name: "complexTool",
+      description: "A complex tool",
+      parameters: z.object({
+        query: z.string().describe("Search query"),
+        filters: z
+          .object({
+            category: z.enum(["books", "movies", "music"]).optional(),
+            minRating: z.number().min(0).max(5).optional(),
+            tags: z.array(z.string()).optional(),
+          })
+          .optional(),
+        pagination: z
+          .object({
+            page: z.number().int().positive().default(1),
+            perPage: z.number().int().positive().default(20),
+          })
+          .optional(),
+      }),
+      execute: async (args) => {
+        return { query: args.query };
+      },
+    });
+
+    expect(tool.name).toBe("complexTool");
+    expect(tool.parameters["~standard"].vendor).toBe("zod");
+    expect(tool.parameters["~standard"].version).toBe(1);
+  });
+
+  it("Zod schema with discriminated union", () => {
+    const tool = defineTool({
+      name: "actionTool",
+      description: "An action tool",
+      parameters: z.object({
+        action: z.discriminatedUnion("type", [
+          z.object({ type: z.literal("search"), query: z.string() }),
+          z.object({ type: z.literal("navigate"), url: z.string().url() }),
+          z.object({
+            type: z.literal("execute"),
+            code: z.string(),
+            language: z.enum(["javascript", "python"]),
+          }),
+        ]),
+      }),
+      execute: async (args) => {
+        return { action: args.action.type };
+      },
+    });
+
+    expect(tool.name).toBe("actionTool");
+    expect(tool.parameters["~standard"].vendor).toBe("zod");
+  });
+
+  it("Zod schema with nullable and record fields", () => {
+    const tool = defineTool({
+      name: "flexTool",
+      description: "Flexible tool",
+      parameters: z.object({
+        title: z.string(),
+        description: z.string().nullable(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+      }),
+      execute: async (args) => {
+        return { title: args.title };
+      },
+    });
+
+    expect(tool.name).toBe("flexTool");
+    expect(tool.parameters["~standard"].vendor).toBe("zod");
+  });
+
+  it("execute callback receives correctly typed args", async () => {
+    const receivedArgs: unknown[] = [];
+
+    const tool = defineTool({
+      name: "argCapture",
+      description: "Captures args",
+      parameters: z.object({
+        city: z.string(),
+        units: z.enum(["celsius", "fahrenheit"]),
+      }),
+      execute: async (args) => {
+        receivedArgs.push(args);
+        return { temp: 22 };
+      },
+    });
+
+    await tool.execute({ city: "Berlin", units: "celsius" });
+
+    expect(receivedArgs).toHaveLength(1);
+    expect(receivedArgs[0]).toEqual({ city: "Berlin", units: "celsius" });
+  });
+});
+
+describe("convertToolDefinitionsToVercelAITools Zod regression", () => {
+  it("Zod schemas are passed directly to AI SDK (not converted via JSON Schema)", () => {
+    const zodSchema = z.object({
+      city: z.string(),
+      units: z.enum(["celsius", "fahrenheit"]).optional(),
+    });
+
+    const tools = [
+      defineTool({
+        name: "weather",
+        description: "Get weather",
+        parameters: zodSchema,
+        execute: async () => ({ temp: 22 }),
+      }),
+    ];
+
+    const aiTools = convertToolDefinitionsToVercelAITools(tools);
+
+    expect(aiTools).toHaveProperty("weather");
+    // The inputSchema should be the original Zod schema (passed directly),
+    // NOT a jsonSchema() wrapper. We verify by checking the Zod-specific
+    // ~standard.vendor property is preserved on the schema.
+    const inputSchema = aiTools.weather.inputSchema;
+    expect(inputSchema).toBeDefined();
+    // For Zod schemas, the AI SDK receives the raw Zod object (which has ~standard.vendor === "zod")
+    // If it went through jsonSchema(), it would lose the ~standard property
+    expect(inputSchema["~standard"]?.vendor).toBe("zod");
+  });
+
+  it("multiple Zod tools all get direct pass-through", () => {
+    const tools = [
+      defineTool({
+        name: "tool1",
+        description: "Tool 1",
+        parameters: z.object({ a: z.string() }),
+        execute: async () => ({}),
+      }),
+      defineTool({
+        name: "tool2",
+        description: "Tool 2",
+        parameters: z.object({ b: z.number(), c: z.boolean().optional() }),
+        execute: async () => ({}),
+      }),
+      defineTool({
+        name: "tool3",
+        description: "Tool 3",
+        parameters: z.object({
+          nested: z.object({ x: z.number(), y: z.number() }),
+        }),
+        execute: async () => ({}),
+      }),
+    ];
+
+    const aiTools = convertToolDefinitionsToVercelAITools(tools);
+
+    for (const name of ["tool1", "tool2", "tool3"]) {
+      expect(aiTools).toHaveProperty(name);
+      expect(aiTools[name].inputSchema["~standard"]?.vendor).toBe("zod");
+      expect(typeof aiTools[name].execute).toBe("function");
+    }
+  });
+
+  it("preserves tool description and execute function", () => {
+    const executeFn = vi.fn().mockResolvedValue({ result: "ok" });
+
+    const tools = [
+      defineTool({
+        name: "myTool",
+        description: "My custom tool description",
+        parameters: z.object({ input: z.string() }),
+        execute: executeFn,
+      }),
+    ];
+
+    const aiTools = convertToolDefinitionsToVercelAITools(tools);
+
+    expect(aiTools.myTool.description).toBe("My custom tool description");
+    expect(aiTools.myTool.execute).toBeDefined();
+  });
+});
+
+describe("BuiltInAgent Zod regression", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+    process.env.OPENAI_API_KEY = "test-key";
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it("Zod tools are included in streamText call", async () => {
+    const agent = new BuiltInAgent({
+      model: "openai/gpt-4o",
+      tools: [
+        defineTool({
+          name: "weather",
+          description: "Get weather",
+          parameters: z.object({
+            city: z.string(),
+            units: z.enum(["celsius", "fahrenheit"]).optional(),
+          }),
+          execute: async () => ({ temp: 22 }),
+        }),
+      ],
+    });
+
+    vi.mocked(streamText).mockReturnValue(
+      mockStreamTextResponse([finish()]) as any,
+    );
+
+    const input: RunAgentInput = {
+      threadId: "thread1",
+      runId: "run1",
+      messages: [],
+      tools: [],
+      context: [],
+      state: {},
+    };
+
+    await collectEvents(agent["run"](input));
+
+    const callArgs = vi.mocked(streamText).mock.calls[0][0];
+    expect(callArgs.tools).toHaveProperty("weather");
+    expect(typeof callArgs.tools?.weather.execute).toBe("function");
+  });
+
+  it("multiple Zod tools coexist with built-in state tools", async () => {
+    const agent = new BuiltInAgent({
+      model: "openai/gpt-4o",
+      tools: [
+        defineTool({
+          name: "search",
+          description: "Search",
+          parameters: z.object({ query: z.string() }),
+          execute: async () => ({}),
+        }),
+        defineTool({
+          name: "calculate",
+          description: "Calculate",
+          parameters: z.object({
+            expression: z.string(),
+            precision: z.number().int().optional(),
+          }),
+          execute: async () => ({}),
+        }),
+      ],
+    });
+
+    vi.mocked(streamText).mockReturnValue(
+      mockStreamTextResponse([finish()]) as any,
+    );
+
+    const input: RunAgentInput = {
+      threadId: "thread1",
+      runId: "run1",
+      messages: [],
+      tools: [],
+      context: [],
+      state: {},
+    };
+
+    await collectEvents(agent["run"](input));
+
+    const callArgs = vi.mocked(streamText).mock.calls[0][0];
+    // User-defined Zod tools
+    expect(callArgs.tools).toHaveProperty("search");
+    expect(callArgs.tools).toHaveProperty("calculate");
+    // Built-in state tools
+    expect(callArgs.tools).toHaveProperty("AGUISendStateSnapshot");
+    expect(callArgs.tools).toHaveProperty("AGUISendStateDelta");
+  });
+
+  it("Zod tool execute is invocable after conversion", async () => {
+    const executeFn = vi.fn().mockResolvedValue({ temp: 22 });
+
+    const agent = new BuiltInAgent({
+      model: "openai/gpt-4o",
+      tools: [
+        defineTool({
+          name: "weather",
+          description: "Get weather",
+          parameters: z.object({ city: z.string() }),
+          execute: executeFn,
+        }),
+      ],
+    });
+
+    vi.mocked(streamText).mockReturnValue(
+      mockStreamTextResponse([finish()]) as any,
+    );
+
+    const input: RunAgentInput = {
+      threadId: "thread1",
+      runId: "run1",
+      messages: [],
+      tools: [],
+      context: [],
+      state: {},
+    };
+
+    await collectEvents(agent["run"](input));
+
+    const callArgs = vi.mocked(streamText).mock.calls[0][0];
+    const weatherTool = callArgs.tools?.weather;
+
+    // Invoke the execute function to verify it's wired correctly
+    await weatherTool.execute({ city: "Berlin" });
+    expect(executeFn).toHaveBeenCalledWith({ city: "Berlin" });
+  });
+});

package/src/index.ts

@@ -42,7 +42,14 @@ import { createOpenAI } from "@ai-sdk/openai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { randomUUID } from "crypto";
+import { safeParseToolArgs } from "@copilotkitnext/shared";
 import { z } from "zod";
+import type {
+  StandardSchemaV1,
+  InferSchemaOutput,
+} from "@copilotkitnext/shared";
+import { schemaToJsonSchema } from "@copilotkitnext/shared";
+import { jsonSchema as aiJsonSchema } from "ai";
 import {
   StreamableHTTPClientTransport,
   StreamableHTTPClientTransportOptions,
@@ -224,27 +231,27 @@ export function resolveModel(
  * Tool definition for BuiltInAgent
  */
 export interface ToolDefinition<
-  TParameters extends z.ZodTypeAny = z.ZodTypeAny,
+  TParameters extends StandardSchemaV1 = StandardSchemaV1,
 > {
   name: string;
   description: string;
   parameters: TParameters;
-  execute: (args: z.infer<TParameters>) => Promise<unknown>;
+  execute: (args: InferSchemaOutput<TParameters>) => Promise<unknown>;
 }
 
 /**
  * Define a tool for use with BuiltInAgent
  * @param name - The name of the tool
  * @param description - Description of what the tool does
- * @param parameters - Zod schema for the tool's input parameters
+ * @param parameters - Schema for the tool's input parameters (any Standard Schema V1 compatible library: Zod, Valibot, ArkType, etc.)
  * @param execute - Function to execute the tool server-side
  * @returns Tool definition
  */
-export function defineTool<TParameters extends z.ZodTypeAny>(config: {
+export function defineTool<TParameters extends StandardSchemaV1>(config: {
   name: string;
   description: string;
   parameters: TParameters;
-  execute: (args: z.infer<TParameters>) => Promise<unknown>;
+  execute: (args: InferSchemaOutput<TParameters>) => Promise<unknown>;
 }): ToolDefinition<TParameters> {
   return {
     name: config.name,
@@ -327,7 +334,7 @@ export function convertMessagesToVercelAISDKMessages(
           type: "tool-call",
           toolCallId: toolCall.id,
           toolName: toolCall.function.name,
-          input: JSON.parse(toolCall.function.arguments),
+          input: safeParseToolArgs(toolCall.function.arguments),
         };
         parts.push(toolCallPart);
       }
@@ -480,7 +487,18 @@ export function convertToolsToVercelAITools(
 }
 
 /**
- * Converts ToolDefinition array to Vercel AI SDK ToolSet
+ * Check whether a schema is a Zod schema by inspecting its Standard Schema vendor.
+ */
+function isZodSchema(schema: StandardSchemaV1): boolean {
+  return schema["~standard"]?.vendor === "zod";
+}
+
+/**
+ * Converts ToolDefinition array to Vercel AI SDK ToolSet.
+ *
+ * For Zod schemas, passes them directly to the AI SDK (Zod satisfies FlexibleSchema).
+ * For non-Zod schemas, converts to JSON Schema via schemaToJsonSchema() and wraps
+ * with the AI SDK's jsonSchema() helper.
  */
 export function convertToolDefinitionsToVercelAITools(
   tools: ToolDefinition[],
@@ -489,11 +507,22 @@ export function convertToolDefinitionsToVercelAITools(
   const result: Record<string, any> = {};
 
   for (const tool of tools) {
-    result[tool.name] = createVercelAISDKTool({
-      description: tool.description,
-      inputSchema: tool.parameters,
-      execute: tool.execute,
-    });
+    if (isZodSchema(tool.parameters)) {
+      // Zod schemas can be passed directly to AI SDK (satisfies FlexibleSchema)
+      result[tool.name] = createVercelAISDKTool({
+        description: tool.description,
+        inputSchema: tool.parameters as any,
+        execute: tool.execute,
+      });
+    } else {
+      // Non-Zod: convert to JSON Schema and wrap with AI SDK's jsonSchema()
+      const jsonSchemaObj = schemaToJsonSchema(tool.parameters);
+      result[tool.name] = createVercelAISDKTool({
+        description: tool.description,
+        inputSchema: aiJsonSchema(jsonSchemaObj),
+        execute: tool.execute,
+      });
+    }
   }
 
   return result;