@copilotkit/shared 1.54.1 → 1.55.0-next.8

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

@@ -0,0 +1,319 @@
+/**
+ * Regression tests proving that `schemaToJsonSchema` produces identical output
+ * to a direct `zodToJsonSchema` call for all common Zod patterns.
+ *
+ * These tests exist to guarantee that the Standard Schema migration did not
+ * change the JSON Schema output for existing Zod users.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { schemaToJsonSchema } from "../standard-schema";
+
+/**
+ * Helper: call zodToJsonSchema the same way the old code path did, then
+ * compare with the new schemaToJsonSchema path.
+ */
+function expectIdenticalOutput(schema: z.ZodTypeAny) {
+  const direct = zodToJsonSchema(schema, { $refStrategy: "none" });
+  const migrated = schemaToJsonSchema(schema, { zodToJsonSchema });
+  expect(migrated).toEqual(direct);
+}
+
+describe("Zod regression — schemaToJsonSchema produces identical output to direct zodToJsonSchema", () => {
+  describe("simple object schemas", () => {
+    it("required string and number fields", () => {
+      expectIdenticalOutput(z.object({ name: z.string(), age: z.number() }));
+    });
+
+    it("optional fields", () => {
+      expectIdenticalOutput(
+        z.object({
+          city: z.string(),
+          units: z.enum(["celsius", "fahrenheit"]).optional(),
+        }),
+      );
+    });
+
+    it("empty object", () => {
+      expectIdenticalOutput(z.object({}));
+    });
+
+    it("object with default values", () => {
+      expectIdenticalOutput(
+        z.object({
+          page: z.number().default(1),
+          perPage: z.number().default(20),
+          query: z.string(),
+        }),
+      );
+    });
+  });
+
+  describe("nested objects", () => {
+    it("single level nesting", () => {
+      expectIdenticalOutput(
+        z.object({
+          user: z.object({ name: z.string(), email: z.string() }),
+        }),
+      );
+    });
+
+    it("deep nesting", () => {
+      expectIdenticalOutput(
+        z.object({
+          level1: z.object({
+            level2: z.object({
+              level3: z.object({
+                value: z.boolean(),
+              }),
+            }),
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("arrays", () => {
+    it("string array", () => {
+      expectIdenticalOutput(z.object({ tags: z.array(z.string()) }));
+    });
+
+    it("object array", () => {
+      expectIdenticalOutput(
+        z.object({
+          items: z.array(z.object({ id: z.number(), label: z.string() })),
+        }),
+      );
+    });
+
+    it("nested arrays", () => {
+      expectIdenticalOutput(z.object({ matrix: z.array(z.array(z.number())) }));
+    });
+  });
+
+  describe("enums and literals", () => {
+    it("z.enum", () => {
+      expectIdenticalOutput(
+        z.object({ status: z.enum(["active", "inactive", "pending"]) }),
+      );
+    });
+
+    it("z.literal string", () => {
+      expectIdenticalOutput(z.object({ type: z.literal("user") }));
+    });
+
+    it("z.literal number", () => {
+      expectIdenticalOutput(z.object({ version: z.literal(2) }));
+    });
+
+    it("z.nativeEnum", () => {
+      enum Color {
+        Red = "red",
+        Green = "green",
+        Blue = "blue",
+      }
+      expectIdenticalOutput(z.object({ color: z.nativeEnum(Color) }));
+    });
+  });
+
+  describe("unions and discriminated unions", () => {
+    it("z.union of primitives", () => {
+      expectIdenticalOutput(
+        z.object({ value: z.union([z.string(), z.number()]) }),
+      );
+    });
+
+    it("z.union of objects", () => {
+      expectIdenticalOutput(
+        z.object({
+          result: z.union([
+            z.object({ ok: z.literal(true), data: z.string() }),
+            z.object({ ok: z.literal(false), error: z.string() }),
+          ]),
+        }),
+      );
+    });
+
+    it("z.discriminatedUnion", () => {
+      expectIdenticalOutput(
+        z.object({
+          event: z.discriminatedUnion("type", [
+            z.object({
+              type: z.literal("click"),
+              x: z.number(),
+              y: z.number(),
+            }),
+            z.object({ type: z.literal("keypress"), key: z.string() }),
+          ]),
+        }),
+      );
+    });
+  });
+
+  describe("nullable and nullish", () => {
+    it("z.nullable", () => {
+      expectIdenticalOutput(z.object({ bio: z.string().nullable() }));
+    });
+
+    it("z.nullish (optional + nullable)", () => {
+      expectIdenticalOutput(z.object({ nickname: z.string().nullish() }));
+    });
+  });
+
+  describe("records and tuples", () => {
+    it("z.record", () => {
+      expectIdenticalOutput(
+        z.object({ metadata: z.record(z.string(), z.unknown()) }),
+      );
+    });
+
+    it("z.tuple", () => {
+      expectIdenticalOutput(
+        z.object({ point: z.tuple([z.number(), z.number()]) }),
+      );
+    });
+  });
+
+  describe("intersections", () => {
+    it("z.intersection", () => {
+      expectIdenticalOutput(
+        z.intersection(
+          z.object({ id: z.number() }),
+          z.object({ name: z.string() }),
+        ),
+      );
+    });
+  });
+
+  describe("string constraints", () => {
+    it("z.string with min/max", () => {
+      expectIdenticalOutput(z.object({ username: z.string().min(3).max(20) }));
+    });
+
+    it("z.string with email", () => {
+      expectIdenticalOutput(z.object({ email: z.string().email() }));
+    });
+
+    it("z.string with url", () => {
+      expectIdenticalOutput(z.object({ website: z.string().url() }));
+    });
+
+    it("z.string with regex", () => {
+      expectIdenticalOutput(
+        z.object({ code: z.string().regex(/^[A-Z]{3}-\d{4}$/) }),
+      );
+    });
+  });
+
+  describe("number constraints", () => {
+    it("z.number with min/max", () => {
+      expectIdenticalOutput(z.object({ score: z.number().min(0).max(100) }));
+    });
+
+    it("z.number.int", () => {
+      expectIdenticalOutput(z.object({ count: z.number().int() }));
+    });
+
+    it("z.number.positive", () => {
+      expectIdenticalOutput(z.object({ amount: z.number().positive() }));
+    });
+  });
+
+  describe("catchall and passthrough", () => {
+    it("z.object with catchall", () => {
+      expectIdenticalOutput(z.object({}).catchall(z.string()));
+    });
+
+    it("z.object with passthrough", () => {
+      expectIdenticalOutput(z.object({ id: z.number() }).passthrough());
+    });
+  });
+
+  describe("z.any and z.unknown", () => {
+    it("z.any", () => {
+      expectIdenticalOutput(z.any());
+    });
+
+    it("z.unknown", () => {
+      expectIdenticalOutput(z.unknown());
+    });
+
+    it("object with z.any field", () => {
+      expectIdenticalOutput(z.object({ data: z.any() }));
+    });
+  });
+
+  describe("complex real-world schemas", () => {
+    it("tool-like schema with multiple field types", () => {
+      expectIdenticalOutput(
+        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(),
+          sortBy: z.enum(["relevance", "date", "rating"]).default("relevance"),
+        }),
+      );
+    });
+
+    it("CopilotKit-like weather tool schema", () => {
+      expectIdenticalOutput(
+        z.object({
+          city: z.string().describe("The city to get weather for"),
+          units: z
+            .enum(["celsius", "fahrenheit"])
+            .optional()
+            .describe("Temperature units"),
+        }),
+      );
+    });
+
+    it("agent-like action schema with nested results", () => {
+      expectIdenticalOutput(
+        z.object({
+          action: z.discriminatedUnion("type", [
+            z.object({
+              type: z.literal("search"),
+              query: z.string(),
+              maxResults: z.number().int().optional(),
+            }),
+            z.object({
+              type: z.literal("navigate"),
+              url: z.string().url(),
+            }),
+            z.object({
+              type: z.literal("execute"),
+              code: z.string(),
+              language: z.enum(["javascript", "python", "shell"]),
+            }),
+          ]),
+          context: z.record(z.string(), z.unknown()).optional(),
+        }),
+      );
+    });
+  });
+
+  describe("described schemas (common in tool definitions)", () => {
+    it("preserves .describe() metadata", () => {
+      expectIdenticalOutput(
+        z
+          .object({
+            city: z.string().describe("The city name"),
+            count: z.number().describe("Number of results"),
+          })
+          .describe("Weather tool parameters"),
+      );
+    });
+  });
+});

package/src/constants/index.ts

@@ -3,3 +3,8 @@ export const COPILOT_CLOUD_VERSION = "v1";
 export const COPILOT_CLOUD_CHAT_URL = `${COPILOT_CLOUD_API_URL}/copilotkit/${COPILOT_CLOUD_VERSION}`;
 export const COPILOT_CLOUD_PUBLIC_API_KEY_HEADER =
   "X-CopilotCloud-Public-Api-Key";
+
+export const DEFAULT_AGENT_ID = "default";
+
+/** Phoenix channel event name used for all AG-UI events. */
+export const AG_UI_CHANNEL_EVENT = "ag-ui";

package/src/finalize-events.ts

@@ -0,0 +1,154 @@
+import { BaseEvent, EventType, RunErrorEvent } from "@ag-ui/client";
+import { randomUUID } from "./utils";
+
+interface FinalizeRunOptions {
+  stopRequested?: boolean;
+  interruptionMessage?: string;
+}
+
+const defaultStopMessage = "Run stopped by user";
+const defaultAbruptEndMessage = "Run ended without emitting a terminal event";
+
+export function finalizeRunEvents(
+  events: BaseEvent[],
+  options: FinalizeRunOptions = {},
+): BaseEvent[] {
+  const { stopRequested = false, interruptionMessage } = options;
+
+  const resolvedStopMessage = interruptionMessage ?? defaultStopMessage;
+  const resolvedAbruptMessage =
+    interruptionMessage && interruptionMessage !== defaultStopMessage
+      ? interruptionMessage
+      : defaultAbruptEndMessage;
+
+  const appended: BaseEvent[] = [];
+
+  const openMessageIds = new Set<string>();
+  const openToolCalls = new Map<
+    string,
+    {
+      hasEnd: boolean;
+      hasResult: boolean;
+    }
+  >();
+
+  for (const event of events) {
+    switch (event.type) {
+      case EventType.TEXT_MESSAGE_START: {
+        const messageId = (event as { messageId?: string }).messageId;
+        if (typeof messageId === "string") {
+          openMessageIds.add(messageId);
+        }
+        break;
+      }
+      case EventType.TEXT_MESSAGE_END: {
+        const messageId = (event as { messageId?: string }).messageId;
+        if (typeof messageId === "string") {
+          openMessageIds.delete(messageId);
+        }
+        break;
+      }
+      case EventType.TOOL_CALL_START: {
+        const toolCallId = (event as { toolCallId?: string }).toolCallId;
+        if (typeof toolCallId === "string") {
+          openToolCalls.set(toolCallId, {
+            hasEnd: false,
+            hasResult: false,
+          });
+        }
+        break;
+      }
+      case EventType.TOOL_CALL_END: {
+        const toolCallId = (event as { toolCallId?: string }).toolCallId;
+        const info = toolCallId ? openToolCalls.get(toolCallId) : undefined;
+        if (info) {
+          info.hasEnd = true;
+        }
+        break;
+      }
+      case EventType.TOOL_CALL_RESULT: {
+        const toolCallId = (event as { toolCallId?: string }).toolCallId;
+        const info = toolCallId ? openToolCalls.get(toolCallId) : undefined;
+        if (info) {
+          info.hasResult = true;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const hasRunFinished = events.some(
+    (event) => event.type === EventType.RUN_FINISHED,
+  );
+  const hasRunError = events.some(
+    (event) => event.type === EventType.RUN_ERROR,
+  );
+  const hasTerminalEvent = hasRunFinished || hasRunError;
+  const terminalEventMissing = !hasTerminalEvent;
+
+  for (const messageId of openMessageIds) {
+    const endEvent = {
+      type: EventType.TEXT_MESSAGE_END,
+      messageId,
+    } as BaseEvent;
+    events.push(endEvent);
+    appended.push(endEvent);
+  }
+
+  for (const [toolCallId, info] of openToolCalls) {
+    if (!info.hasEnd) {
+      const endEvent = {
+        type: EventType.TOOL_CALL_END,
+        toolCallId,
+      } as BaseEvent;
+      events.push(endEvent);
+      appended.push(endEvent);
+    }
+
+    if (terminalEventMissing && !info.hasResult) {
+      const resultEvent = {
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId,
+        messageId: `${toolCallId ?? randomUUID()}-result`,
+        role: "tool",
+        content: JSON.stringify(
+          stopRequested
+            ? {
+                status: "stopped",
+                reason: "stop_requested",
+                message: resolvedStopMessage,
+              }
+            : {
+                status: "error",
+                reason: "missing_terminal_event",
+                message: resolvedAbruptMessage,
+              },
+        ),
+      } as BaseEvent;
+      events.push(resultEvent);
+      appended.push(resultEvent);
+    }
+  }
+
+  if (terminalEventMissing) {
+    if (stopRequested) {
+      const finishedEvent = {
+        type: EventType.RUN_FINISHED,
+      } as BaseEvent;
+      events.push(finishedEvent);
+      appended.push(finishedEvent);
+    } else {
+      const errorEvent: RunErrorEvent = {
+        type: EventType.RUN_ERROR,
+        message: resolvedAbruptMessage,
+        code: "INCOMPLETE_STREAM",
+      };
+      events.push(errorEvent);
+      appended.push(errorEvent);
+    }
+  }
+
+  return appended;
+}

package/src/index.ts

@@ -2,6 +2,18 @@ export * from "./types";
 export * from "./utils";
 export * from "./constants";
 export * from "./telemetry";
+export * from "./standard-schema";
+
+export { logger } from "./logger";
+export { finalizeRunEvents } from "./finalize-events";
+
+export {
+  TranscriptionErrorCode,
+  TranscriptionErrors,
+  type TranscriptionErrorResponse,
+} from "./transcription-errors";
 
 import * as packageJson from "../package.json";
 export const COPILOTKIT_VERSION = packageJson.version;
+
+export * from "@copilotkit/license-verifier";

package/src/logger.ts

@@ -0,0 +1 @@
+export const logger = console;

package/src/standard-schema.ts

@@ -0,0 +1,76 @@
+import type {
+  StandardSchemaV1,
+  StandardJSONSchemaV1,
+} from "@standard-schema/spec";
+
+export type { StandardSchemaV1, StandardJSONSchemaV1 };
+
+/**
+ * Extract the Output type from a StandardSchemaV1 schema.
+ * Replaces `z.infer<S>` for generic schema inference.
+ */
+export type InferSchemaOutput<S> =
+  S extends StandardSchemaV1<any, infer O> ? O : never;
+
+export interface SchemaToJsonSchemaOptions {
+  /**
+   * Injected `zodToJsonSchema` function so that `shared` does not depend on
+   * `zod-to-json-schema`. Required when the schema is a Zod v3 schema that
+   * does not implement Standard JSON Schema V1.
+   */
+  zodToJsonSchema?: (
+    schema: unknown,
+    options?: { $refStrategy?: string },
+  ) => Record<string, unknown>;
+}
+
+/**
+ * Check whether a schema implements the Standard JSON Schema V1 protocol.
+ */
+function hasStandardJsonSchema(
+  schema: StandardSchemaV1,
+): schema is StandardSchemaV1 & StandardJSONSchemaV1 {
+  const props = schema["~standard"];
+  return (
+    props != null &&
+    typeof props === "object" &&
+    "jsonSchema" in props &&
+    props.jsonSchema != null &&
+    typeof props.jsonSchema === "object" &&
+    "input" in props.jsonSchema &&
+    typeof props.jsonSchema.input === "function"
+  );
+}
+
+/**
+ * Convert any StandardSchemaV1-compatible schema to a JSON Schema object.
+ *
+ * Strategy:
+ * 1. If the schema implements Standard JSON Schema V1 (`~standard.jsonSchema`),
+ *    call `schema['~standard'].jsonSchema.input({ target: 'draft-07' })`.
+ * 2. If the schema is a Zod v3 schema (`~standard.vendor === 'zod'`), use the
+ *    injected `zodToJsonSchema()` function.
+ * 3. Otherwise throw a descriptive error.
+ */
+export function schemaToJsonSchema(
+  schema: StandardSchemaV1,
+  options?: SchemaToJsonSchemaOptions,
+): Record<string, unknown> {
+  // 1. Standard JSON Schema V1
+  if (hasStandardJsonSchema(schema)) {
+    return schema["~standard"].jsonSchema.input({ target: "draft-07" });
+  }
+
+  // 2. Zod v3 fallback
+  const vendor = schema["~standard"].vendor;
+  if (vendor === "zod" && options?.zodToJsonSchema) {
+    return options.zodToJsonSchema(schema, { $refStrategy: "none" });
+  }
+
+  throw new Error(
+    `Cannot convert schema to JSON Schema. The schema (vendor: "${vendor}") does not implement Standard JSON Schema V1 ` +
+      `and no zodToJsonSchema fallback is available. ` +
+      `Use a library that supports Standard JSON Schema (e.g., Zod 3.24+, Valibot v1+, ArkType v2+) ` +
+      `or pass a zodToJsonSchema function in options.`,
+  );
+}

package/src/transcription-errors.ts

@@ -0,0 +1,99 @@
+/**
+ * Error codes for transcription HTTP responses.
+ * Uses snake_case to align with existing CopilotKitCoreErrorCode pattern.
+ * These codes are returned by the runtime and parsed by the client.
+ */
+export enum TranscriptionErrorCode {
+  /** Transcription service not configured in runtime */
+  SERVICE_NOT_CONFIGURED = "service_not_configured",
+  /** Audio format not supported */
+  INVALID_AUDIO_FORMAT = "invalid_audio_format",
+  /** Audio file is too long */
+  AUDIO_TOO_LONG = "audio_too_long",
+  /** Audio file is empty or too short */
+  AUDIO_TOO_SHORT = "audio_too_short",
+  /** Rate limited by transcription provider */
+  RATE_LIMITED = "rate_limited",
+  /** Authentication failed with transcription provider */
+  AUTH_FAILED = "auth_failed",
+  /** Transcription provider returned an error */
+  PROVIDER_ERROR = "provider_error",
+  /** Network error during transcription */
+  NETWORK_ERROR = "network_error",
+  /** Invalid request format */
+  INVALID_REQUEST = "invalid_request",
+}
+
+/**
+ * Error response format returned by the transcription endpoint.
+ */
+export interface TranscriptionErrorResponse {
+  error: TranscriptionErrorCode;
+  message: string;
+  retryable?: boolean;
+}
+
+/**
+ * Helper functions to create transcription error responses.
+ * Used by the runtime to return consistent error responses.
+ */
+export const TranscriptionErrors = {
+  serviceNotConfigured: (): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.SERVICE_NOT_CONFIGURED,
+    message: "Transcription service is not configured",
+    retryable: false,
+  }),
+
+  invalidAudioFormat: (
+    format: string,
+    supported: string[],
+  ): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.INVALID_AUDIO_FORMAT,
+    message: `Unsupported audio format: ${format}. Supported: ${supported.join(", ")}`,
+    retryable: false,
+  }),
+
+  invalidRequest: (details: string): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.INVALID_REQUEST,
+    message: details,
+    retryable: false,
+  }),
+
+  rateLimited: (): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.RATE_LIMITED,
+    message: "Rate limited. Please try again later.",
+    retryable: true,
+  }),
+
+  authFailed: (): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.AUTH_FAILED,
+    message: "Authentication failed with transcription provider",
+    retryable: false,
+  }),
+
+  providerError: (message: string): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.PROVIDER_ERROR,
+    message,
+    retryable: true,
+  }),
+
+  networkError: (
+    message: string = "Network error during transcription",
+  ): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.NETWORK_ERROR,
+    message,
+    retryable: true,
+  }),
+
+  audioTooLong: (): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.AUDIO_TOO_LONG,
+    message: "Audio file is too long",
+    retryable: false,
+  }),
+
+  audioTooShort: (): TranscriptionErrorResponse => ({
+    error: TranscriptionErrorCode.AUDIO_TOO_SHORT,
+    message: "Audio is too short to transcribe",
+    retryable: false,
+  }),
+};

package/src/types/message.ts

@@ -1,4 +1,4 @@
-import agui from "@ag-ui/core";
+import * as agui from "@ag-ui/core";
 
 export interface ImageData {
   format: string;