@librechat/agents 3.2.64 → 3.2.65

package/src/llm/anthropic/utils/stream_events.ts

@@ -0,0 +1,471 @@
+/**
+ * Converts a raw Anthropic SSE event stream into LangChain ChatModelStreamEvents.
+ *
+ * @module
+ */
+
+import type {
+  ChatModelStreamEvent,
+  ContentBlockDelta,
+  FinishReason,
+} from '@langchain/core/language_models/event';
+import type { ContentBlock, UsageMetadata } from '@langchain/core/messages';
+import type {
+  AnthropicCompactionBlock,
+  AnthropicCompactionContentBlockDelta,
+  AnthropicMessageStreamEvent,
+} from '../types';
+import type { AnthropicUsageData } from './message_outputs';
+import { getAnthropicUsageMetadata } from './message_outputs';
+
+type AnthropicContentBlock =
+  | Extract<
+      AnthropicMessageStreamEvent,
+      { type: 'content_block_start' }
+    >['content_block']
+  | AnthropicCompactionBlock;
+
+type AnthropicContentDelta =
+  | Extract<
+      AnthropicMessageStreamEvent,
+      { type: 'content_block_delta' }
+    >['delta']
+  | AnthropicCompactionContentBlockDelta;
+
+interface AnthropicStreamErrorEvent {
+  type: 'error';
+  error: {
+    type: string;
+    message: string;
+  };
+  request_id?: string | null;
+}
+
+type AnthropicStreamInputEvent =
+  | AnthropicMessageStreamEvent
+  | AnthropicStreamErrorEvent;
+
+type BlockAccumulator = Record<string, unknown>;
+
+interface AnthropicEventUsage {
+  inputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  outputTokens: number;
+}
+
+// ─── Public API ─────────────────────────────────────────────────
+
+export interface ConvertAnthropicStreamOptions {
+  streamUsage?: boolean;
+}
+
+/**
+ * Convert an async iterable of raw Anthropic stream events into
+ * LangChain `ChatModelStreamEvent`s with typed deltas.
+ */
+export async function* convertAnthropicStream(
+  source: AsyncIterable<AnthropicStreamInputEvent>,
+  options: ConvertAnthropicStreamOptions = {}
+): AsyncGenerator<ChatModelStreamEvent> {
+  const shouldStreamUsage = options.streamUsage ?? true;
+
+  // Track accumulated state per content block (for finalization)
+  const blockAccumulators = new Map<number, BlockAccumulator>();
+  let usageSnapshot: UsageMetadata | undefined;
+  let eventUsage: AnthropicEventUsage | undefined;
+  let stopReason: string | null = null;
+
+  for await (const data of source) {
+    switch (data.type) {
+    // ── Message lifecycle ──────────────────────────────────
+    case 'message_start': {
+      const { usage, id, model } = data.message;
+      if (shouldStreamUsage) {
+        eventUsage = {
+          inputTokens: usage.input_tokens,
+          cacheCreationInputTokens: usage.cache_creation_input_tokens ?? 0,
+          cacheReadInputTokens: usage.cache_read_input_tokens ?? 0,
+          outputTokens: usage.output_tokens,
+        };
+        usageSnapshot = buildUsageSnapshot(eventUsage);
+      }
+      yield {
+        event: 'message-start' as const,
+        id,
+        ...(usageSnapshot ? { usage: usageSnapshot } : {}),
+      };
+      yield {
+        event: 'provider' as const,
+        provider: 'anthropic',
+        name: 'message_start',
+        payload: { model, id },
+      };
+      break;
+    }
+
+    case 'message_delta': {
+      stopReason = data.delta.stop_reason;
+      if (shouldStreamUsage) {
+        eventUsage = updateEventUsage(eventUsage, data.usage);
+        usageSnapshot = buildUsageSnapshot(eventUsage);
+        yield { event: 'usage' as const, usage: usageSnapshot };
+      }
+      if (
+        'context_management' in data.delta &&
+          data.delta.context_management != null
+      ) {
+        yield {
+          event: 'provider' as const,
+          provider: 'anthropic',
+          name: 'context_management',
+          payload: data.delta.context_management,
+        };
+      }
+      break;
+    }
+
+    case 'message_stop': {
+      const finishEvent = {
+        event: 'message-finish' as const,
+        reason: mapStopReason(stopReason),
+        ...(usageSnapshot ? { usage: usageSnapshot } : {}),
+        responseMetadata: { model_provider: 'anthropic' },
+      };
+      yield finishEvent;
+      break;
+    }
+
+    case 'error': {
+      const streamError = new Error(data.error.message);
+      streamError.name = data.error.type;
+      throw streamError;
+    }
+
+    // ── Content block lifecycle ───────────────────────────
+    case 'content_block_start': {
+      const { index, content_block } = data;
+      const mapped = mapBlockToContentBlock(content_block, index);
+      blockAccumulators.set(index, { ...mapped });
+      yield {
+        event: 'content-block-start' as const,
+        index,
+        content: mapped as unknown as ContentBlock,
+      };
+      break;
+    }
+
+    case 'content_block_delta': {
+      const { index, delta } = data;
+      const acc = blockAccumulators.get(index);
+      if (!acc) break;
+
+      const { contentDelta, accumulated } = applyAnthropicDelta(acc, delta);
+      blockAccumulators.set(index, accumulated);
+
+      yield {
+        event: 'content-block-delta' as const,
+        index,
+        delta: contentDelta,
+      };
+      break;
+    }
+
+    case 'content_block_stop': {
+      const { index } = data;
+      const acc = blockAccumulators.get(index);
+      if (!acc) break;
+
+      const finalized = finalizeBlock(acc);
+      yield {
+        event: 'content-block-finish' as const,
+        index,
+        content: finalized,
+      };
+      blockAccumulators.delete(index);
+      break;
+    }
+
+    // ── Unhandled → provider passthrough ───────────────────
+    default: {
+      const providerData = data as AnthropicMessageStreamEvent;
+      yield {
+        event: 'provider' as const,
+        provider: 'anthropic',
+        name: providerData.type,
+        payload: providerData,
+      };
+      break;
+    }
+    }
+  }
+}
+
+// ─── Internal helpers ───────────────────────────────────────────
+
+function mapStopReason(stopReason: string | null | undefined): FinishReason {
+  switch (stopReason) {
+  case 'end_turn':
+  case 'stop_sequence':
+    return 'stop';
+  case 'tool_use':
+    return 'tool_use';
+  case 'max_tokens':
+  case 'model_context_window_exceeded':
+    return 'length';
+  case 'refusal':
+    return 'content_filter';
+  default:
+    return 'stop';
+  }
+}
+
+function updateEventUsage(
+  previous: AnthropicEventUsage | undefined,
+  current: AnthropicUsageData
+): AnthropicEventUsage {
+  return {
+    inputTokens: getCumulativeUsageValue(
+      current.input_tokens,
+      previous?.inputTokens
+    ),
+    cacheCreationInputTokens: getCumulativeUsageValue(
+      current.cache_creation_input_tokens,
+      previous?.cacheCreationInputTokens
+    ),
+    cacheReadInputTokens: getCumulativeUsageValue(
+      current.cache_read_input_tokens,
+      previous?.cacheReadInputTokens
+    ),
+    outputTokens: getCumulativeUsageValue(
+      current.output_tokens,
+      previous?.outputTokens
+    ),
+  };
+}
+
+function getCumulativeUsageValue(
+  current: number | null | undefined,
+  previous: number | undefined
+): number {
+  return Math.max(previous ?? 0, current ?? 0);
+}
+
+function buildUsageSnapshot(usage: AnthropicEventUsage): UsageMetadata {
+  const metadata = getAnthropicUsageMetadata({
+    input_tokens: usage.inputTokens,
+    output_tokens: usage.outputTokens,
+    cache_creation_input_tokens: usage.cacheCreationInputTokens,
+    cache_read_input_tokens: usage.cacheReadInputTokens,
+  });
+  if (metadata == null) {
+    throw new Error('Anthropic usage metadata was not created');
+  }
+  return metadata;
+}
+
+function getStringField(record: BlockAccumulator, key: string): string {
+  const value = record[key];
+  return typeof value === 'string' ? value : '';
+}
+
+function getArrayField(record: BlockAccumulator, key: string): unknown[] {
+  const value = record[key];
+  return Array.isArray(value) ? value : [];
+}
+
+function mapBlockToContentBlock(
+  block: AnthropicContentBlock,
+  index: number
+): BlockAccumulator {
+  switch (block.type) {
+  case 'text':
+    return {
+      type: 'text' as const,
+      text: block.text,
+      ...(block.citations != null ? { citations: block.citations } : {}),
+      index,
+    };
+  case 'thinking':
+    return {
+      type: 'reasoning' as const,
+      reasoning: block.thinking,
+      index,
+    };
+  case 'redacted_thinking':
+    return { ...block, index };
+  case 'tool_use':
+    return {
+      type: 'tool_call_chunk' as const,
+      id: block.id,
+      name: block.name,
+      args: '',
+      index,
+    };
+  case 'server_tool_use':
+    return {
+      type: 'server_tool_call_chunk' as const,
+      id: block.id,
+      name: block.name,
+      args: '',
+      index,
+    };
+  case 'web_search_tool_result':
+    return { ...block, index };
+  case 'compaction':
+    return { ...block, index };
+  default:
+    return { type: 'non_standard' as const, value: { ...block }, index };
+  }
+}
+
+/**
+ * Map an Anthropic content_block_delta to a content block delta
+ * and update the accumulated state.
+ */
+function applyAnthropicDelta(
+  accumulated: BlockAccumulator,
+  delta: AnthropicContentDelta
+): {
+  contentDelta: ContentBlockDelta;
+  accumulated: BlockAccumulator;
+} {
+  const rawDelta = delta as unknown as Record<string, unknown>;
+  switch (delta.type) {
+  case 'text_delta':
+    return {
+      contentDelta: { type: 'text-delta' as const, text: delta.text },
+      accumulated: {
+        ...accumulated,
+        text: getStringField(accumulated, 'text') + delta.text,
+      },
+    };
+
+  case 'thinking_delta':
+    return {
+      contentDelta: {
+        type: 'reasoning-delta' as const,
+        reasoning: delta.thinking,
+      },
+      accumulated: {
+        ...accumulated,
+        reasoning: getStringField(accumulated, 'reasoning') + delta.thinking,
+      },
+    };
+
+  case 'input_json_delta': {
+    const newArgs = getStringField(accumulated, 'args') + delta.partial_json;
+    return {
+      contentDelta: {
+        type: 'block-delta' as const,
+        fields: {
+          type: getStringField(accumulated, 'type'),
+          args: newArgs,
+        },
+      },
+      accumulated: { ...accumulated, args: newArgs },
+    };
+  }
+
+  case 'citations_delta': {
+    const citations = [
+      ...getArrayField(accumulated, 'citations'),
+      delta.citation,
+    ];
+    return {
+      contentDelta: {
+        type: 'block-delta' as const,
+        fields: {
+          type: getStringField(accumulated, 'type'),
+          citations,
+        },
+      },
+      accumulated: {
+        ...accumulated,
+        citations,
+      },
+    };
+  }
+
+  case 'signature_delta':
+    return {
+      contentDelta: {
+        type: 'block-delta' as const,
+        fields: {
+          type: getStringField(accumulated, 'type'),
+          signature: delta.signature,
+        },
+      },
+      accumulated: { ...accumulated, signature: delta.signature },
+    };
+
+  case 'compaction_delta': {
+    const previousContent = accumulated.content;
+    const content =
+        delta.content == null
+          ? (previousContent ?? null)
+          : getStringField(accumulated, 'content') + delta.content;
+    return {
+      contentDelta: {
+        type: 'block-delta' as const,
+        fields: {
+          type: 'compaction',
+          content,
+          encrypted_content: delta.encrypted_content,
+        },
+      },
+      accumulated: {
+        ...accumulated,
+        content,
+        encrypted_content: delta.encrypted_content,
+      },
+    };
+  }
+
+  default:
+    return {
+      contentDelta: {
+        type: 'block-delta' as const,
+        fields: {
+          type: getStringField(accumulated, 'type'),
+          ...rawDelta,
+        },
+      },
+      accumulated,
+    };
+  }
+}
+
+function finalizeBlock(accumulated: BlockAccumulator): ContentBlock {
+  if (
+    accumulated.type === 'tool_call_chunk' ||
+    accumulated.type === 'server_tool_call_chunk'
+  ) {
+    const finalType =
+      accumulated.type === 'tool_call_chunk'
+        ? ('tool_call' as const)
+        : ('server_tool_call' as const);
+    const args = getStringField(accumulated, 'args');
+    let parsedArgs: unknown;
+    try {
+      parsedArgs = JSON.parse(args || '{}');
+    } catch {
+      return {
+        type: 'invalid_tool_call' as const,
+        id: getStringField(accumulated, 'id'),
+        name: getStringField(accumulated, 'name'),
+        args,
+        error: 'Failed to parse tool call arguments as JSON',
+      } as ContentBlock.Tools.InvalidToolCall;
+    }
+    return {
+      type: finalType,
+      id: getStringField(accumulated, 'id'),
+      name: getStringField(accumulated, 'name'),
+      args: parsedArgs,
+    } as ContentBlock;
+  }
+
+  const { index: _index, ...rest } = accumulated;
+  return rest as ContentBlock;
+}

package/src/tools/search/crw-scraper.ts

@@ -0,0 +1,244 @@
+import axios from 'axios';
+import type * as t from './types';
+import { createDefaultLogger } from './utils';
+import { processContent } from './content';
+
+/** HTTP headroom over the payload render budget: fastCRW's queue/verification
+ * overhead is not counted against `timeout`, so the client must wait longer. */
+const CRW_TIMEOUT_BUFFER = 5000;
+
+/**
+ * fastCRW scraper. Firecrawl-compatible web scraper; single binary;
+ * self-host or cloud. Posts to {base}/v1/scrape.
+ */
+export class CrwScraper implements t.BaseScraper {
+  private apiKey: string;
+  private apiUrl: string;
+  private defaultFormats: string[];
+  private timeout: number;
+  private logger: t.Logger;
+  private onlyMainContent?: boolean;
+  private includeTags?: string[];
+  private excludeTags?: string[];
+  private waitFor?: number;
+  private headers?: Record<string, string>;
+  private renderJs?: boolean | null;
+  private cssSelector?: string;
+  private xpath?: string;
+  private proxy?: string;
+  private stealth?: boolean;
+
+  constructor(config: t.CrwScraperConfig = {}) {
+    this.apiKey = config.apiKey ?? process.env.CRW_API_KEY ?? '';
+
+    const baseUrl =
+      config.apiUrl ?? process.env.CRW_API_URL ?? 'https://api.fastcrw.com';
+    this.apiUrl = `${baseUrl.replace(/\/+$/, '')}/v1/scrape`;
+
+    this.defaultFormats = config.formats ?? ['markdown', 'html'];
+    this.timeout = config.timeout ?? 7500;
+    this.logger = config.logger || createDefaultLogger();
+
+    this.onlyMainContent = config.onlyMainContent;
+    this.includeTags = config.includeTags;
+    this.excludeTags = config.excludeTags;
+    this.waitFor = config.waitFor;
+    this.headers = config.headers;
+    this.renderJs = config.renderJs;
+    this.cssSelector = config.cssSelector;
+    this.xpath = config.xpath;
+    this.proxy = config.proxy;
+    this.stealth = config.stealth;
+
+    // Self-host fastCRW may run without auth, so a missing key is only a
+    // warning — unlike Firecrawl/Tavily, scrapeUrl does NOT early-return on it.
+    if (!this.apiKey) {
+      this.logger.warn('CRW_API_KEY is not set. Scraping will not work.');
+    }
+    this.logger.debug(`CRW scraper initialized with API URL: ${this.apiUrl}`);
+  }
+
+  async scrapeUrl(
+    url: string,
+    options: t.CrwScrapeOptions = {}
+  ): Promise<[string, t.CrwScrapeResponse]> {
+    try {
+      const payloadTimeout = options.timeout ?? this.timeout;
+      const payload = omitUndefined({
+        url,
+        formats: options.formats ?? this.defaultFormats,
+        onlyMainContent: options.onlyMainContent ?? this.onlyMainContent,
+        includeTags: options.includeTags ?? this.includeTags,
+        excludeTags: options.excludeTags ?? this.excludeTags,
+        waitFor: options.waitFor ?? this.waitFor,
+        headers: options.headers ?? this.headers,
+        renderJs: options.renderJs ?? this.renderJs,
+        cssSelector: options.cssSelector ?? this.cssSelector,
+        xpath: options.xpath ?? this.xpath,
+        proxy: options.proxy ?? this.proxy,
+        stealth: options.stealth ?? this.stealth,
+        // Cloud honors `timeout` (live-verified); the published OpenAPI
+        // documents `deadlineMs` (1..60000) instead. Send both.
+        timeout: payloadTimeout,
+        deadlineMs: Math.max(1, Math.min(payloadTimeout, 60000)),
+      });
+
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+      if (this.apiKey) {
+        headers.Authorization = `Bearer ${this.apiKey}`;
+      }
+
+      const response = await axios.post<t.CrwRawScrapeResponse>(
+        this.apiUrl,
+        payload,
+        {
+          headers,
+          timeout: payloadTimeout + CRW_TIMEOUT_BUFFER,
+        }
+      );
+
+      return [url, normalizeCrwResponse(response.data)];
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      return [
+        url,
+        {
+          success: false,
+          error: `fastCRW API request failed: ${errorMessage}`,
+        },
+      ];
+    }
+  }
+
+  /**
+   * Extract content from scrape response. Mirrors FirecrawlScraper — reads
+   * response.data.*, which normalizeCrwResponse guarantees, preserving the
+   * processContent ref-markers used by the reranker. Parameter is typed as the
+   * NARROWER t.CrwScrapeResponse, exactly like TavilyScraper/FirecrawlScraper:
+   * TS class-method bivariance accepts this against BaseScraper's
+   * AnyScraperResponse, AND it lets us read response.data.plainText (a
+   * CrwScrapeResponse-only field) with no cast.
+   */
+  extractContent(
+    response: t.CrwScrapeResponse
+  ): [string, undefined | t.References] {
+    if (!response.success || !response.data) {
+      return ['', undefined];
+    }
+
+    const htmlSource = response.data.html ?? response.data.rawHtml;
+    if (response.data.markdown != null && htmlSource != null) {
+      try {
+        const { markdown, ...rest } = processContent(
+          htmlSource,
+          response.data.markdown
+        );
+        return [markdown, rest];
+      } catch (error) {
+        this.logger.error('Error processing content:', error);
+        return [response.data.markdown, undefined];
+      }
+    } else if (response.data.markdown != null) {
+      return [response.data.markdown, undefined];
+    }
+
+    // Fall back to HTML content
+    if (response.data.html != null) {
+      return [response.data.html, undefined];
+    }
+
+    // Fall back to raw HTML content
+    if (response.data.rawHtml != null) {
+      return [response.data.rawHtml, undefined];
+    }
+
+    // CRW-only fallback (no Firecrawl equivalent): plain-text body.
+    if (response.data.plainText != null) {
+      return [response.data.plainText, undefined];
+    }
+
+    return ['', undefined];
+  }
+
+  extractMetadata(response: t.CrwScrapeResponse): t.ScrapeMetadata {
+    if (!response.success || !response.data || !response.data.metadata) {
+      return {};
+    }
+
+    return response.data.metadata;
+  }
+}
+
+/**
+ * Create a fastCRW scraper instance
+ * @param config Scraper configuration
+ * @returns fastCRW scraper instance
+ */
+export const createCrwScraper = (config: t.CrwScraperConfig = {}): CrwScraper =>
+  new CrwScraper(config);
+
+/**
+ * fastCRW cloud nests scrape fields under `data` ({success, data: {markdown,
+ * ...}}, live-verified 2026-07-02), matching Firecrawl. Prefer the nested
+ * container and fall back to top-level fields for self-host/legacy responses.
+ */
+function normalizeCrwResponse(
+  raw: t.CrwRawScrapeResponse | null | undefined
+): t.CrwScrapeResponse {
+  if (raw == null) {
+    return { success: false, error: 'Empty fastCRW response' };
+  }
+  if (raw.success === false) {
+    return {
+      success: false,
+      error:
+        raw.error_code != null
+          ? `[${raw.error_code}] ${raw.error ?? 'Unknown error'}`
+          : (raw.error ?? 'fastCRW scrape failed'),
+      error_code: raw.error_code,
+    };
+  }
+  const data = raw.data ?? raw;
+  return {
+    success: true,
+    data: {
+      // Strip inline base64 image payloads from text content (not `screenshot`,
+      // which is base64 by design and never reaches the content processor).
+      markdown: stripBase64DataUris(data.markdown),
+      html: stripBase64DataUris(data.html),
+      rawHtml: stripBase64DataUris(data.rawHtml),
+      plainText: stripBase64DataUris(data.plainText),
+      screenshot: data.screenshot,
+      links: data.links,
+      metadata: data.metadata,
+    },
+  };
+}
+
+/**
+ * Replace inline base64 data-URI payloads (typically images) in scraped text
+ * with a short placeholder. Such payloads can be hundreds of KB; the content
+ * processor builds a per-link RegExp from each URL, and one that large overflows
+ * the engine's pattern-size limit ("Invalid regular expression"). Firecrawl
+ * drops them via removeBase64Images — mirror that so image-heavy pages stay
+ * processable (and don't bloat the LLM context with base64 noise).
+ */
+function stripBase64DataUris(text: string | undefined): string | undefined {
+  if (text == null) {
+    return text;
+  }
+  return text.replace(
+    /data:[\w.+-]+\/[\w.+-]+;base64,[A-Za-z0-9+/=]+/g,
+    'data:base64-content-removed'
+  );
+}
+
+// Helper function to clean up payload for fastCRW
+function omitUndefined<T extends object>(obj: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, v]) => v !== undefined)
+  ) as Partial<T>;
+}