assistant-stream 0.2.47 → 0.3.1

package/src/core/converters/toGenericMessages.ts

@@ -0,0 +1,264 @@
+/**
+ * Generic message types for framework-agnostic LLM message interchange.
+ * These types represent a common format that can be converted to/from
+ * various LLM provider formats (AI SDK, LangChain, etc.).
+ */
+
+export type GenericTextPart = {
+  type: "text";
+  text: string;
+};
+
+export type GenericFilePart = {
+  type: "file";
+  data: string | URL;
+  mediaType: string;
+};
+
+export type GenericToolCallPart = {
+  type: "tool-call";
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+};
+
+export type GenericToolResultPart = {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+};
+
+export type GenericSystemMessage = {
+  role: "system";
+  content: string;
+};
+
+export type GenericUserMessage = {
+  role: "user";
+  content: (GenericTextPart | GenericFilePart)[];
+};
+
+export type GenericAssistantMessage = {
+  role: "assistant";
+  content: (GenericTextPart | GenericToolCallPart)[];
+};
+
+export type GenericToolMessage = {
+  role: "tool";
+  content: GenericToolResultPart[];
+};
+
+export type GenericMessage =
+  | GenericSystemMessage
+  | GenericUserMessage
+  | GenericAssistantMessage
+  | GenericToolMessage;
+
+type MessagePartLike = {
+  type: string;
+  text?: string;
+  image?: string;
+  data?: string;
+  mimeType?: string;
+  toolCallId?: string;
+  toolName?: string;
+  args?: Record<string, unknown>;
+  result?: unknown;
+  isError?: boolean;
+};
+
+type AttachmentLike = {
+  content: readonly MessagePartLike[];
+};
+
+type ThreadMessageLike = {
+  role: "system" | "user" | "assistant";
+  content: readonly MessagePartLike[];
+  attachments?: readonly AttachmentLike[];
+};
+
+const IMAGE_MEDIA_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+  tiff: "image/tiff",
+  tif: "image/tiff",
+  heic: "image/heic",
+  heif: "image/heif",
+};
+
+function inferImageMediaType(url: string): string {
+  // Handle data URLs: data:[<mediatype>][;base64],<data>
+  if (url.startsWith("data:")) {
+    const match = url.match(/^data:([^;,]+)/);
+    if (match?.[1]) return match[1];
+  }
+
+  // Extract extension from URL path, ignoring query string and hash
+  const [pathWithoutParams = ""] = url.split(/[?#]/);
+  const ext = pathWithoutParams.split(".").pop()?.toLowerCase() ?? "";
+  return IMAGE_MEDIA_TYPES[ext] ?? "image/png";
+}
+
+function toUrlOrString(value: string): string | URL {
+  try {
+    return new URL(value);
+  } catch {
+    return value;
+  }
+}
+
+type ToolCallAccumulator = {
+  textParts: (GenericTextPart | GenericToolCallPart)[];
+  toolResults: GenericToolResultPart[];
+};
+
+function processToolCall(
+  part: MessagePartLike,
+  accumulator: ToolCallAccumulator,
+): boolean {
+  if (!part.toolCallId || !part.toolName) return false;
+
+  accumulator.textParts.push({
+    type: "tool-call",
+    toolCallId: part.toolCallId,
+    toolName: part.toolName,
+    args: part.args ?? {},
+  });
+
+  if (part.result !== undefined) {
+    const toolResult: GenericToolResultPart = {
+      type: "tool-result",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      result: part.result,
+    };
+    if (part.isError) {
+      toolResult.isError = true;
+    }
+    accumulator.toolResults.push(toolResult);
+    return true;
+  }
+  return false;
+}
+
+function flushAccumulator(
+  accumulator: ToolCallAccumulator,
+  result: GenericMessage[],
+): void {
+  if (accumulator.textParts.length > 0) {
+    result.push({ role: "assistant", content: accumulator.textParts });
+    accumulator.textParts = [];
+  }
+  if (accumulator.toolResults.length > 0) {
+    result.push({ role: "tool", content: accumulator.toolResults });
+    accumulator.toolResults = [];
+  }
+}
+
+function convertSystemMessage(
+  message: ThreadMessageLike,
+  result: GenericMessage[],
+): void {
+  const textPart = message.content.find((p) => p.type === "text");
+  if (textPart?.text) {
+    result.push({ role: "system", content: textPart.text });
+  }
+}
+
+function convertUserMessage(
+  message: ThreadMessageLike,
+  result: GenericMessage[],
+): void {
+  const attachments = message.attachments ?? [];
+  const allContent = [
+    ...message.content,
+    ...attachments.flatMap((a) => a.content),
+  ];
+
+  const content: (GenericTextPart | GenericFilePart)[] = [];
+
+  for (const part of allContent) {
+    if (part.type === "text" && part.text) {
+      content.push({ type: "text", text: part.text });
+    } else if (part.type === "image" && part.image) {
+      content.push({
+        type: "file",
+        data: toUrlOrString(part.image),
+        mediaType: inferImageMediaType(part.image),
+      });
+    } else if (part.type === "file" && part.data && part.mimeType) {
+      content.push({
+        type: "file",
+        data: toUrlOrString(part.data),
+        mediaType: part.mimeType,
+      });
+    }
+  }
+
+  if (content.length > 0) {
+    result.push({ role: "user", content });
+  }
+}
+
+function convertAssistantMessage(
+  message: ThreadMessageLike,
+  result: GenericMessage[],
+): void {
+  const accumulator: ToolCallAccumulator = {
+    textParts: [],
+    toolResults: [],
+  };
+  let hasPendingToolResults = false;
+
+  for (const part of message.content) {
+    if (part.type === "text" && part.text) {
+      // Flush pending tool results before adding more text
+      if (hasPendingToolResults) {
+        flushAccumulator(accumulator, result);
+        hasPendingToolResults = false;
+      }
+      accumulator.textParts.push({ type: "text", text: part.text });
+    } else if (part.type === "tool-call") {
+      if (processToolCall(part, accumulator)) {
+        hasPendingToolResults = true;
+      }
+    }
+  }
+
+  flushAccumulator(accumulator, result);
+}
+
+/**
+ * Converts thread messages to generic LLM messages.
+ * This format can then be easily converted to provider-specific formats.
+ */
+export function toGenericMessages(
+  messages: readonly ThreadMessageLike[],
+): GenericMessage[] {
+  const result: GenericMessage[] = [];
+
+  for (const message of messages) {
+    switch (message.role) {
+      case "system":
+        convertSystemMessage(message, result);
+        break;
+      case "user":
+        convertUserMessage(message, result);
+        break;
+      case "assistant":
+        convertAssistantMessage(message, result);
+        break;
+    }
+  }
+
+  return result;
+}

package/src/core/index.ts

@@ -38,3 +38,5 @@ export {
   fromObjectStreamResponse,
 } from "./object/ObjectStreamResponse";
 export type { ObjectStreamChunk } from "./object/types";
+
+export * from "./converters";

package/src/core/tool/index.ts

@@ -7,3 +7,9 @@ export {
   unstable_runPendingTools,
   type ToolResultStreamOptions,
 } from "./toolResultStream";
+export {
+  toJSONSchema,
+  toToolsJSONSchema,
+  type ToolJSONSchema,
+  type ToToolsJSONSchemaOptions,
+} from "./schema-utils";

package/src/core/tool/schema-utils.test.ts

@@ -0,0 +1,382 @@
+import { describe, expect, it } from "vitest";
+import { toJSONSchema, toToolsJSONSchema } from "./schema-utils";
+import type { Tool } from "./tool-types";
+
+describe("toJSONSchema", () => {
+  it("converts StandardSchemaV1 with ~standard.toJSONSchema", () => {
+    const mockStandardSchema = {
+      "~standard": {
+        version: 1,
+        vendor: "test",
+        validate: () => ({ value: {} }),
+        toJSONSchema: () => ({
+          type: "object",
+          properties: { name: { type: "string" } },
+        }),
+      },
+    };
+
+    const result = toJSONSchema(mockStandardSchema);
+    expect(result).toEqual({
+      type: "object",
+      properties: { name: { type: "string" } },
+    });
+  });
+
+  it("converts object with toJSONSchema() method", () => {
+    const schemaWithMethod = {
+      toJSONSchema: () => ({
+        type: "object",
+        properties: { age: { type: "number" } },
+      }),
+    };
+
+    const result = toJSONSchema(schemaWithMethod as never);
+    expect(result).toEqual({
+      type: "object",
+      properties: { age: { type: "number" } },
+    });
+  });
+
+  it("converts object with toJSON() method", () => {
+    const schemaWithToJSON = {
+      toJSON: () => ({
+        type: "object",
+        properties: { active: { type: "boolean" } },
+      }),
+    };
+
+    const result = toJSONSchema(schemaWithToJSON as never);
+    expect(result).toEqual({
+      type: "object",
+      properties: { active: { type: "boolean" } },
+    });
+  });
+
+  it("passes through plain JSONSchema7", () => {
+    const plainSchema = {
+      type: "object" as const,
+      properties: {
+        email: { type: "string" as const, format: "email" },
+      },
+      required: ["email"],
+    };
+
+    const result = toJSONSchema(plainSchema);
+    expect(result).toEqual(plainSchema);
+  });
+
+  it("prioritizes StandardSchema over toJSONSchema method", () => {
+    const mixedSchema = {
+      "~standard": {
+        version: 1,
+        vendor: "test",
+        validate: () => ({ value: {} }),
+        toJSONSchema: () => ({ type: "string", description: "from standard" }),
+      },
+      toJSONSchema: () => ({ type: "number", description: "from method" }),
+    };
+
+    const result = toJSONSchema(mixedSchema);
+    expect(result).toEqual({ type: "string", description: "from standard" });
+  });
+
+  it("prioritizes toJSONSchema over toJSON method", () => {
+    const mixedSchema = {
+      toJSONSchema: () => ({
+        type: "string",
+        description: "from toJSONSchema",
+      }),
+      toJSON: () => ({ type: "number", description: "from toJSON" }),
+    };
+
+    const result = toJSONSchema(mixedSchema as never);
+    expect(result).toEqual({
+      type: "string",
+      description: "from toJSONSchema",
+    });
+  });
+
+  it("falls back to plain schema when StandardSchema has no toJSONSchema", () => {
+    const schemaWithoutMethod = {
+      "~standard": {
+        version: 1,
+        vendor: "test",
+        validate: () => ({ value: {} }),
+        // no toJSONSchema method
+      },
+      type: "object" as const,
+      properties: {},
+    };
+
+    const result = toJSONSchema(schemaWithoutMethod);
+    // Should return the object as-is since ~standard.toJSONSchema is not a function
+    expect(result).toEqual(schemaWithoutMethod);
+  });
+});
+
+describe("toToolsJSONSchema", () => {
+  describe("filtering", () => {
+    it("excludes disabled tools by default", () => {
+      const tools: Record<string, Tool> = {
+        enabledTool: {
+          description: "Enabled tool",
+          parameters: { type: "object", properties: {} },
+        },
+        disabledTool: {
+          disabled: true,
+          description: "Disabled tool",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toHaveProperty("enabledTool");
+      expect(result).not.toHaveProperty("disabledTool");
+    });
+
+    it("excludes backend tools by default", () => {
+      const tools: Record<string, Tool> = {
+        frontendTool: {
+          type: "frontend",
+          description: "Frontend tool",
+          parameters: { type: "object", properties: {} },
+        },
+        backendTool: {
+          type: "backend",
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toHaveProperty("frontendTool");
+      expect(result).not.toHaveProperty("backendTool");
+    });
+
+    it("includes frontend tools", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          type: "frontend",
+          description: "A frontend tool",
+          parameters: { type: "object", properties: { x: { type: "number" } } },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toEqual({
+        myTool: {
+          description: "A frontend tool",
+          parameters: { type: "object", properties: { x: { type: "number" } } },
+        },
+      });
+    });
+
+    it("includes human tools", () => {
+      const tools: Record<string, Tool> = {
+        humanTool: {
+          type: "human",
+          description: "A human tool",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toHaveProperty("humanTool");
+    });
+
+    it("excludes tools without parameters", () => {
+      const tools: Record<string, Tool> = {
+        withParams: {
+          description: "With params",
+          parameters: { type: "object", properties: {} },
+        },
+        withoutParams: {
+          type: "backend",
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toHaveProperty("withParams");
+      expect(result).not.toHaveProperty("withoutParams");
+    });
+
+    it("respects custom filter function", () => {
+      const tools: Record<string, Tool> = {
+        tool_a: {
+          disabled: true,
+          parameters: { type: "object", properties: {} },
+        },
+        tool_b: {
+          type: "backend",
+        },
+        tool_c: {
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      // Custom filter that includes all tools regardless of disabled/backend
+      const result = toToolsJSONSchema(tools, {
+        filter: () => true,
+      });
+
+      // tool_a and tool_c have parameters, tool_b does not
+      expect(result).toHaveProperty("tool_a");
+      expect(result).not.toHaveProperty("tool_b"); // still excluded due to no parameters
+      expect(result).toHaveProperty("tool_c");
+    });
+
+    it("custom filter receives name and tool", () => {
+      const tools: Record<string, Tool> = {
+        prefixed_tool: {
+          description: "Should include",
+          parameters: { type: "object", properties: {} },
+        },
+        other_tool: {
+          description: "Should exclude",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools, {
+        filter: (name, tool) =>
+          name.startsWith("prefixed_") && tool.description !== undefined,
+      });
+
+      expect(result).toHaveProperty("prefixed_tool");
+      expect(result).not.toHaveProperty("other_tool");
+    });
+  });
+
+  describe("output format", () => {
+    it("includes description when present", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          description: "This is my tool",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool).toEqual({
+        description: "This is my tool",
+        parameters: { type: "object", properties: {} },
+      });
+    });
+
+    it("omits description when absent", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool).toEqual({
+        parameters: { type: "object", properties: {} },
+      });
+      expect(result.myTool).not.toHaveProperty("description");
+    });
+
+    it("omits description when empty string", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          description: "",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool).not.toHaveProperty("description");
+    });
+
+    it("converts parameters via toJSONSchema", () => {
+      const mockStandardSchema = {
+        "~standard": {
+          version: 1,
+          vendor: "test",
+          validate: () => ({ value: {} }),
+          toJSONSchema: () => ({
+            type: "object",
+            properties: { converted: { type: "boolean" } },
+          }),
+        },
+      };
+
+      const tools: Record<string, Tool> = {
+        myTool: {
+          description: "Test",
+          parameters: mockStandardSchema,
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result.myTool!.parameters).toEqual({
+        type: "object",
+        properties: { converted: { type: "boolean" } },
+      });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns empty object for undefined tools", () => {
+      const result = toToolsJSONSchema(undefined);
+      expect(result).toEqual({});
+    });
+
+    it("returns empty object for empty tools", () => {
+      const result = toToolsJSONSchema({});
+      expect(result).toEqual({});
+    });
+
+    it("returns empty object when all tools are filtered out", () => {
+      const tools: Record<string, Tool> = {
+        disabled1: {
+          disabled: true,
+          parameters: { type: "object", properties: {} },
+        },
+        disabled2: {
+          disabled: true,
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toEqual({});
+    });
+
+    it("handles tools with undefined type (defaults to frontend behavior)", () => {
+      const tools: Record<string, Tool> = {
+        myTool: {
+          // no type specified
+          description: "Tool without type",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(result).toHaveProperty("myTool");
+    });
+
+    it("handles multiple tools correctly", () => {
+      const tools: Record<string, Tool> = {
+        tool_1: {
+          description: "First tool",
+          parameters: { type: "object", properties: { a: { type: "string" } } },
+        },
+        tool_2: {
+          description: "Second tool",
+          parameters: { type: "object", properties: { b: { type: "number" } } },
+        },
+        tool_3: {
+          disabled: true,
+          parameters: { type: "object", properties: {} },
+        },
+      };
+
+      const result = toToolsJSONSchema(tools);
+      expect(Object.keys(result)).toHaveLength(2);
+      expect(result).toHaveProperty("tool_1");
+      expect(result).toHaveProperty("tool_2");
+      expect(result).not.toHaveProperty("tool_3");
+    });
+  });
+});