@ai-sdk/langchain 2.0.214 → 2.0.216

package/src/types.ts

@@ -28,6 +28,20 @@ export interface LangGraphEventState {
   currentStep: number | null;
   /** Maps tool call key (name:argsJson) to tool call ID for HITL interrupt handling */
   emittedToolCallsByKey: Map<string, string>;
+  /** Tracks source IDs already emitted to avoid duplicates across messages/values events */
+  emittedSourceIds: Set<string>;
+}
+
+/**
+ * A LangChain citation projected to the fields the AI SDK source parts can carry.
+ */
+export interface NormalizedCitation {
+  url?: string;
+  title?: string;
+  source?: string;
+  citedText?: string;
+  startIndex?: number;
+  endIndex?: number;
 }
 
 /**

package/src/utils.ts

@@ -14,15 +14,18 @@ import {
   type ToolResultPart,
   type AssistantContent,
   type UserContent,
+  type ProviderMetadata,
+  type JSONValue,
 } from 'ai';
 
-import type {
-  LangGraphEventState,
-  LangGraphMessageSeen,
-  ReasoningContentBlock,
-  ThinkingContentBlock,
-  GPT5ReasoningOutput,
-  ImageGenerationOutput,
+import {
+  type LangGraphEventState,
+  type LangGraphMessageSeen,
+  type ReasoningContentBlock,
+  type ThinkingContentBlock,
+  type GPT5ReasoningOutput,
+  type ImageGenerationOutput,
+  type NormalizedCitation,
 } from './types';
 
 /**
@@ -394,6 +397,7 @@ export function processModelChunk(
     /** Track the ID used for text-start to ensure text-end uses the same ID */
     textMessageId?: string | null;
     emittedImages?: Set<string>;
+    emittedSourceIds?: Set<string>;
   },
   controller: ReadableStreamDefaultController<UIMessageChunk>,
 ): void {
@@ -404,6 +408,10 @@ export function processModelChunk(
     state.emittedImages = new Set<string>();
   }
 
+  if (!state.emittedSourceIds) {
+    state.emittedSourceIds = new Set<string>();
+  }
+
   /**
    * Get the message ID from the chunk if available
    */
@@ -507,6 +515,16 @@ export function processModelChunk(
       id: state.textMessageId ?? state.messageId,
     });
   }
+
+  const citations = extractCitationsFromContentBlocks(chunk);
+  if (citations.length > 0) {
+    emitSourceChunks(
+      citations,
+      state.messageId,
+      state.emittedSourceIds,
+      controller,
+    );
+  }
 }
 
 /**
@@ -921,6 +939,152 @@ export function extractReasoningFromValuesMessage(
   return undefined;
 }
 
+export function isCitationContentBlock(
+  obj: unknown,
+): obj is ContentBlock.Citation {
+  return (
+    obj != null &&
+    typeof obj === 'object' &&
+    'type' in obj &&
+    (obj as { type: unknown }).type === 'citation'
+  );
+}
+
+/**
+ * LangChain Core standardizes citations as `{ type: 'citation', ... }` entries in
+ * the `annotations` array of a text content block. The text extractors elsewhere
+ * in this file only read the `text` field, so without this the citations would be
+ * dropped instead of surfaced as AI SDK source parts.
+ *
+ * Handles both class instances and serialized LangChain message objects.
+ */
+export function extractCitationsFromContentBlocks(
+  msg: unknown,
+): NormalizedCitation[] {
+  if (msg == null || typeof msg !== 'object') return [];
+
+  const msgObj = msg as Record<string, unknown>;
+  const kwargs =
+    msgObj.kwargs && typeof msgObj.kwargs === 'object'
+      ? (msgObj.kwargs as Record<string, unknown>)
+      : msgObj;
+
+  // `contentBlocks` is the normalized view derived from `content`; reading both
+  // would double-count annotations, so prefer it and only fall back to `content`.
+  const contentBlocks = (kwargs as { contentBlocks?: unknown }).contentBlocks;
+  const content = (kwargs as { content?: unknown }).content;
+  const blockSources: unknown[] = Array.isArray(contentBlocks)
+    ? contentBlocks
+    : Array.isArray(content)
+      ? content
+      : [];
+
+  const citations: NormalizedCitation[] = [];
+
+  for (const block of blockSources) {
+    if (block == null || typeof block !== 'object') continue;
+
+    const annotations = (block as { annotations?: unknown }).annotations;
+    if (!Array.isArray(annotations)) continue;
+
+    for (const annotation of annotations) {
+      if (!isCitationContentBlock(annotation)) continue;
+
+      citations.push({
+        url: annotation.url,
+        title: annotation.title,
+        source: annotation.source,
+        citedText: annotation.citedText,
+        startIndex: annotation.startIndex,
+        endIndex: annotation.endIndex,
+      });
+    }
+  }
+
+  return citations;
+}
+
+function buildSourceProviderMetadata(
+  citation: NormalizedCitation,
+): ProviderMetadata | undefined {
+  const langchain: Record<string, JSONValue> = {};
+
+  if (typeof citation.citedText === 'string') {
+    langchain.citedText = citation.citedText;
+  }
+  if (typeof citation.startIndex === 'number') {
+    langchain.startIndex = citation.startIndex;
+  }
+  if (typeof citation.endIndex === 'number') {
+    langchain.endIndex = citation.endIndex;
+  }
+  if (typeof citation.source === 'string') {
+    langchain.source = citation.source;
+  }
+
+  if (Object.keys(langchain).length === 0) {
+    return undefined;
+  }
+
+  return { langchain };
+}
+
+/**
+ * Emits AI SDK source chunks (`source-url` / `source-document`) for the given
+ * citations.
+ *
+ * Citations with a `url` become `source-url` parts keyed by that url; the rest
+ * become `source-document` parts. Citation metadata that the source parts cannot
+ * represent natively (`citedText`, `startIndex`, `endIndex`, `source`) is preserved
+ * under `providerMetadata.langchain`.
+ *
+ * `emittedSourceIds` dedupes across the LangGraph messages and values events, which
+ * can each surface the same citation. URL-less citations are keyed by their content
+ * rather than position, so a differing citation subset/order between those two events
+ * does not cause an id collision.
+ */
+export function emitSourceChunks(
+  citations: NormalizedCitation[],
+  messageId: string,
+  emittedSourceIds: Set<string>,
+  controller: ReadableStreamDefaultController<UIMessageChunk>,
+): void {
+  for (const citation of citations) {
+    if (citation.url) {
+      if (emittedSourceIds.has(citation.url)) continue;
+      emittedSourceIds.add(citation.url);
+
+      const providerMetadata = buildSourceProviderMetadata(citation);
+      controller.enqueue({
+        type: 'source-url',
+        sourceId: citation.url,
+        url: citation.url,
+        ...(citation.title ? { title: citation.title } : {}),
+        ...(providerMetadata ? { providerMetadata } : {}),
+      });
+      continue;
+    }
+
+    // A citation with no url and no human-readable label carries no information a
+    // UI could render, so skip it rather than emit a placeholder source.
+    const title = citation.title ?? citation.source;
+    if (!title) continue;
+
+    const sourceId = `${messageId}:${title}:${citation.citedText ?? ''}:${citation.startIndex ?? ''}:${citation.endIndex ?? ''}`;
+    if (emittedSourceIds.has(sourceId)) continue;
+    emittedSourceIds.add(sourceId);
+
+    const providerMetadata = buildSourceProviderMetadata(citation);
+    controller.enqueue({
+      type: 'source-document',
+      sourceId,
+      mediaType: 'text/plain',
+      title,
+      ...(providerMetadata ? { providerMetadata } : {}),
+    });
+  }
+}
+
 /**
  * Checks if an object is an image generation output
  *
@@ -1293,6 +1457,16 @@ export function processLangGraphEvent(
             id: msgId,
           });
         }
+
+        const citations = extractCitationsFromContentBlocks(msg);
+        if (citations.length > 0) {
+          emitSourceChunks(
+            citations,
+            msgId,
+            state.emittedSourceIds,
+            controller,
+          );
+        }
       } else if (isToolMessageType(msg)) {
         // Handle both direct properties and serialized messages (kwargs)
         const msgObj = msg as unknown as Record<string, unknown>;
@@ -1572,6 +1746,16 @@ export function processLangGraphEvent(
                 emittedReasoningIds.add(reasoningId);
               }
             }
+
+            const valuesCitations = extractCitationsFromContentBlocks(msg);
+            if (valuesCitations.length > 0) {
+              emitSourceChunks(
+                valuesCitations,
+                msgId,
+                state.emittedSourceIds,
+                controller,
+              );
+            }
           }
         }
       }