fix: annotation schema to support file annotations

- Define a new `annotations` schema with support for `url_citation` and `file` types.
- Adjust chat handling logic to parse and accommodate file annotations.
- Update tests for both `url_citation` and `file` annotations.

Author: Leward

src/chat/index.test.ts

@@ -1,5 +1,6 @@
 import type { LanguageModelV2Prompt } from '@ai-sdk/provider';
 import type { ReasoningDetailUnion } from '../schemas/reasoning-details';
+import type { AnnotationUnion } from '../schemas/annotations';
 
 import {
   convertReadableStreamToArray,
@@ -131,6 +132,7 @@ describe('doGenerate', () => {
     reasoning,
     reasoning_details,
     images,
+    annotations,
     usage = {
       prompt_tokens: 4,
       total_tokens: 34,
@@ -143,6 +145,7 @@ describe('doGenerate', () => {
     reasoning?: string;
     reasoning_details?: Array<ReasoningDetailUnion>;
     images?: Array<ImageResponse>;
+    annotations?: Array<AnnotationUnion>;
     usage?: {
       prompt_tokens: number;
       total_tokens: number;
@@ -175,6 +178,7 @@ describe('doGenerate', () => {
               reasoning,
               reasoning_details,
               images,
+              annotations,
             },
             logprobs,
             finish_reason,
@@ -612,6 +616,73 @@ describe('doGenerate', () => {
       },
     ]);
   });
+
+  it('should handle file annotations', async () => {
+    prepareJsonResponse({
+      content: 'Here is the document summary.',
+      annotations: [
+        {
+          type: 'file',
+          file: {
+            hash: '666ad042331aa9cfd0a5d334fc96825be408e71a428f7508225d99d4354e202c',
+            name: 'document.pdf',
+            content: [{ type: 'text', text: 'Sample document content' }],
+          },
+        },
+      ],
+    });
+
+    const result = await model.doGenerate({
+      prompt: TEST_PROMPT,
+    });
+
+    expect(result.content).toStrictEqual([
+      {
+        type: 'text',
+        text: 'Here is the document summary.',
+      },
+    ]);
+  });
+
+  it('should handle url_citation annotations', async () => {
+    prepareJsonResponse({
+      content: 'Here is some information from a source.',
+      annotations: [
+        {
+          type: 'url_citation',
+          url_citation: {
+            end_index: 414,
+            start_index: 327,
+            title: 'What to see at Berlin Art Week 2025 | Wallpaper*',
+            url: 'https://www.wallpaper.com/art/exhibitions-shows/berlin-art-week-2025',
+          },
+        },
+      ],
+    });
+
+    const result = await model.doGenerate({
+      prompt: TEST_PROMPT,
+    });
+
+    expect(result.content).toStrictEqual([
+      {
+        type: 'text',
+        text: 'Here is some information from a source.',
+      },
+      {
+        type: 'source',
+        sourceType: 'url',
+        id: 'https://www.wallpaper.com/art/exhibitions-shows/berlin-art-week-2025',
+        url: 'https://www.wallpaper.com/art/exhibitions-shows/berlin-art-week-2025',
+        title: 'What to see at Berlin Art Week 2025 | Wallpaper*',
+        providerMetadata: {
+          openrouter: {
+            content: '',
+          },
+        },
+      },
+    ]);
+  });
 });
 
 describe('doStream', () => {
@@ -899,8 +970,8 @@ describe('doStream', () => {
     // 5. text-delta (2 times)
     // 6. text-end (when stream finishes)
 
-    const streamOrder = elements.map(el => el.type);
-    
+    const streamOrder = elements.map((el) => el.type);
+
     // Find the positions of key events
     const reasoningStartIndex = streamOrder.indexOf('reasoning-start');
     const reasoningEndIndex = streamOrder.indexOf('reasoning-end');
@@ -926,10 +997,7 @@ describe('doStream', () => {
       .filter((el) => el.type === 'text-delta')
       .map((el) => (el as { type: 'text-delta'; delta: string }).delta);
 
-    expect(textDeltas).toEqual([
-      'Hello! ',
-      'How can I help you today?',
-    ]);
+    expect(textDeltas).toEqual(['Hello! ', 'How can I help you today?']);
   });
 
   it('should stream tool deltas', async () => {

src/chat/index.ts

@@ -351,6 +351,9 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
               },
             },
           });
+        } else if (annotation.type === 'file') {
+          // File annotations are handled but not currently converted to content
+          // This allows the schema to parse them without breaking
         }
       }
     }
@@ -648,6 +651,9 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
                       },
                     },
                   });
+                } else if (annotation.type === 'file') {
+                  // File annotations are handled but not currently converted to stream events
+                  // This allows the schema to parse them without breaking
                 }
               }
             }
@@ -788,7 +794,7 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
                   type: 'file',
                   mediaType: getMediaType(image.image_url.url, 'image/jpeg'),
                   data: getBase64FromDataUrl(image.image_url.url),
-                })
+                });
               }
             }
           },
@@ -832,12 +838,12 @@ export class OpenRouterChatLanguageModel implements LanguageModelV2 {
             } = {
               usage: openrouterUsage,
             };
-            
+
             // Only include provider if it's actually set
             if (provider !== undefined) {
               openrouterMetadata.provider = provider;
             }
-            
+
             controller.enqueue({
               type: 'finish',
               finishReason,

src/chat/schemas.ts

@@ -2,6 +2,7 @@ import { z } from 'zod/v4';
 import { OpenRouterErrorResponseSchema } from '../schemas/error-response';
 import { ReasoningDetailArraySchema } from '../schemas/reasoning-details';
 import { ImageResponseArraySchema } from '../schemas/image';
+import { AnnotationArraySchema } from '../schemas/annotations';
 
 const OpenRouterChatCompletionBaseResponseSchema = z.object({
   id: z.string().optional(),
@@ -43,6 +44,7 @@ export const OpenRouterNonStreamChatCompletionResponseSchema =
           reasoning: z.string().nullable().optional(),
           reasoning_details: ReasoningDetailArraySchema.nullish(),
           images: ImageResponseArraySchema.nullish(),
+          annotations: AnnotationArraySchema.nullish(),
 
           tool_calls: z
             .array(
@@ -56,21 +58,6 @@ export const OpenRouterNonStreamChatCompletionResponseSchema =
               }),
             )
             .optional(),
-
-          annotations: z
-            .array(
-              z.object({
-                type: z.enum(['url_citation']),
-                url_citation: z.object({
-                  end_index: z.number(),
-                  start_index: z.number(),
-                  title: z.string(),
-                  url: z.string(),
-                  content: z.string().optional(),
-                }),
-              }),
-            )
-            .nullish(),
         }),
         index: z.number().nullish(),
         logprobs: z
@@ -109,6 +96,7 @@ export const OpenRouterStreamChatCompletionChunkSchema = z.union([
             reasoning: z.string().nullish().optional(),
             reasoning_details: ReasoningDetailArraySchema.nullish(),
             images: ImageResponseArraySchema.nullish(),
+            annotations: AnnotationArraySchema.nullish(),
             tool_calls: z
               .array(
                 z.object({
@@ -122,21 +110,6 @@ export const OpenRouterStreamChatCompletionChunkSchema = z.union([
                 }),
               )
               .nullish(),
-
-            annotations: z
-              .array(
-                z.object({
-                  type: z.enum(['url_citation']),
-                  url_citation: z.object({
-                    end_index: z.number(),
-                    start_index: z.number(),
-                    title: z.string(),
-                    url: z.string(),
-                    content: z.string().optional(),
-                  }),
-                }),
-              )
-              .nullish(),
           })
           .nullish(),
         logprobs: z

src/schemas/annotations.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod/v4';
+
+export const UrlCitationAnnotationSchema = z.object({
+  type: z.literal('url_citation'),
+  url_citation: z.object({
+    end_index: z.number(),
+    start_index: z.number(),
+    title: z.string(),
+    url: z.string(),
+    content: z.string().optional(),
+  }),
+});
+
+export const FileAnnotationSchema = z.object({
+  type: z.literal('file'),
+  file: z.object({
+    hash: z.string(),
+    name: z.string(),
+    content: z.array(z.record(z.string(), z.unknown())).optional(),
+  }),
+});
+
+export const AnnotationUnionSchema = z.discriminatedUnion('type', [
+  UrlCitationAnnotationSchema,
+  FileAnnotationSchema,
+]);
+
+export type AnnotationUnion = z.infer<typeof AnnotationUnionSchema>;
+
+export const AnnotationArraySchema = z.array(AnnotationUnionSchema);