@librechat/agents 3.2.33 → 3.2.35

package/dist/esm/utils/tokens.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.mjs","names":[],"sources":["../../../src/utils/tokens.ts"],"sourcesContent":["import { Tokenizer } from 'ai-tokenizer';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { ContentTypes } from '@/common/enum';\n\nexport type EncodingName = 'o200k_base' | 'claude';\n\n/** Anthropic minimum image token cost. */\nconst ANTHROPIC_IMAGE_MIN_TOKENS = 1024;\n/** Anthropic divisor: tokens = width × height / 750. */\nconst ANTHROPIC_IMAGE_DIVISOR = 750;\n/** OpenAI low-detail fixed cost. */\nconst OPENAI_IMAGE_LOW_TOKENS = 85;\n/** OpenAI high-detail tile size. */\nconst OPENAI_IMAGE_TILE_SIZE = 512;\n/** OpenAI high-detail tokens per tile. */\nconst OPENAI_IMAGE_TOKENS_PER_TILE = 170;\n/** Google Gemini fixed per-image cost. */\nconst _GEMINI_IMAGE_TOKENS = 258;\n/** Safety margin for image and document token estimates (5% overestimate). */\nconst IMAGE_TOKEN_SAFETY_MARGIN = 1.05;\n\n/**\n * Anthropic PDF: each page costs image tokens + text tokens.\n * Typical range is 1500-3000 tokens/page. Using 2000 as midpoint.\n */\nconst ANTHROPIC_PDF_TOKENS_PER_PAGE = 2000;\n/** OpenAI PDF: each page rendered as high-detail image. ~1500 tokens typical. */\nconst OPENAI_PDF_TOKENS_PER_PAGE = 1500;\n/** Gemini PDF: fixed 258 tokens per page. */\nconst _GEMINI_PDF_TOKENS_PER_PAGE = 258;\n/** Approximate base64 bytes per PDF page for page count estimation. */\nconst BASE64_BYTES_PER_PDF_PAGE = 75_000;\n/** Fallback token cost for URL-referenced documents without local data. */\nconst URL_DOCUMENT_FALLBACK_TOKENS = 2000;\n\n/**\n * Extracts image dimensions from the first bytes of a base64-encoded\n * PNG, JPEG, GIF, or WebP without decoding the full image.\n * Returns null if the format is unrecognized or data is too short.\n */\nexport function extractImageDimensions(\n  base64Data: string\n): { width: number; height: number } | null {\n  const raw = base64Data.startsWith('data:')\n    ? base64Data.slice(base64Data.indexOf(',') + 1)\n    : base64Data;\n\n  if (raw.length < 32) {\n    return null;\n  }\n\n  const bytes = new Uint8Array(Buffer.from(raw.slice(0, 80), 'base64'));\n\n  if (bytes[0] === 0x89 && bytes[1] === 0x50) {\n    // PNG: width at bytes 16-19, height at 20-23 (big-endian)\n    const width =\n      (bytes[16] << 24) | (bytes[17] << 16) | (bytes[18] << 8) | bytes[19];\n    const height =\n      (bytes[20] << 24) | (bytes[21] << 16) | (bytes[22] << 8) | bytes[23];\n    return { width, height };\n  }\n\n  if (bytes[0] === 0xff && bytes[1] === 0xd8) {\n    // JPEG: scan for SOF0 (0xFFC0) or SOF2 (0xFFC2) marker\n    for (let i = 2; i < bytes.length - 9; i++) {\n      if (\n        bytes[i] === 0xff &&\n        (bytes[i + 1] === 0xc0 || bytes[i + 1] === 0xc2)\n      ) {\n        const height = (bytes[i + 5] << 8) | bytes[i + 6];\n        const width = (bytes[i + 7] << 8) | bytes[i + 8];\n        return { width, height };\n      }\n    }\n    return null;\n  }\n\n  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {\n    // GIF: width at bytes 6-7, height at 8-9 (little-endian)\n    const width = bytes[6] | (bytes[7] << 8);\n    const height = bytes[8] | (bytes[9] << 8);\n    return { width, height };\n  }\n\n  if (\n    bytes[0] === 0x52 &&\n    bytes[1] === 0x49 &&\n    bytes[2] === 0x46 &&\n    bytes[3] === 0x46 &&\n    bytes[8] === 0x57 &&\n    bytes[9] === 0x45 &&\n    bytes[10] === 0x42 &&\n    bytes[11] === 0x50\n  ) {\n    // WebP VP8: width at bytes 26-27, height at 28-29\n    if (bytes.length > 29) {\n      const width = (bytes[26] | (bytes[27] << 8)) & 0x3fff;\n      const height = (bytes[28] | (bytes[29] << 8)) & 0x3fff;\n      return { width, height };\n    }\n    return null;\n  }\n\n  return null;\n}\n\n/** Estimates image token cost for Anthropic/Bedrock (Claude). */\nexport function estimateAnthropicImageTokens(\n  width: number,\n  height: number\n): number {\n  return Math.max(\n    ANTHROPIC_IMAGE_MIN_TOKENS,\n    Math.ceil((width * height) / ANTHROPIC_IMAGE_DIVISOR)\n  );\n}\n\n/** Estimates image token cost for OpenAI (high detail). */\nexport function estimateOpenAIImageTokens(\n  width: number,\n  height: number,\n  detail: string = 'high'\n): number {\n  if (detail === 'low') {\n    return OPENAI_IMAGE_LOW_TOKENS;\n  }\n  const tiles =\n    Math.ceil(width / OPENAI_IMAGE_TILE_SIZE) *\n    Math.ceil(height / OPENAI_IMAGE_TILE_SIZE);\n  return OPENAI_IMAGE_LOW_TOKENS + tiles * OPENAI_IMAGE_TOKENS_PER_TILE;\n}\n\n/**\n * Estimates token cost for an image content block.\n * Extracts dimensions from base64 header when available.\n * Falls back to Anthropic minimum (1024) when dimensions can't be determined.\n */\nfunction estimateImageBlockTokens(\n  block: Record<string, unknown>,\n  encoding: EncodingName\n): number {\n  let base64Data: string | undefined;\n\n  if (block.type === ContentTypes.IMAGE_URL || block.type === 'image_url') {\n    const imageUrl = block.image_url as string | { url?: string } | undefined;\n    const url = typeof imageUrl === 'string' ? imageUrl : imageUrl?.url;\n    if (typeof url === 'string' && url.startsWith('data:')) {\n      base64Data = url;\n    } else {\n      return ANTHROPIC_IMAGE_MIN_TOKENS;\n    }\n  } else if (block.type === 'image') {\n    const source = block.source as { type?: string; data?: string } | undefined;\n    if (source?.type === 'base64' && typeof source.data === 'string') {\n      base64Data = source.data;\n    } else {\n      return ANTHROPIC_IMAGE_MIN_TOKENS;\n    }\n  } else {\n    return ANTHROPIC_IMAGE_MIN_TOKENS;\n  }\n\n  const dims = extractImageDimensions(base64Data);\n  if (dims == null) {\n    return ANTHROPIC_IMAGE_MIN_TOKENS;\n  }\n\n  if (encoding === 'claude') {\n    return estimateAnthropicImageTokens(dims.width, dims.height);\n  }\n  return estimateOpenAIImageTokens(dims.width, dims.height);\n}\n\n/**\n * Estimates token cost for a document/file content block.\n * Handles both LangChain standard format (`type: 'file'` with `source_type`)\n * and Anthropic format (`type: 'document'` with `source`).\n *\n * - Plain text: tokenized directly via `getTokenCount`.\n * - Base64 PDF: page count estimated from base64 length × per-page cost.\n * - URL reference: conservative flat estimate.\n */\nfunction estimateDocumentBlockTokens(\n  block: Record<string, unknown>,\n  encoding: EncodingName,\n  getTokenCount: (text: string) => number\n): number {\n  const pdfTokensPerPage =\n    encoding === 'claude'\n      ? ANTHROPIC_PDF_TOKENS_PER_PAGE\n      : OPENAI_PDF_TOKENS_PER_PAGE;\n\n  // LangChain standard format: type='file', source_type, data/text/url, mime_type\n  const sourceType = block.source_type as string | undefined;\n  if (typeof sourceType === 'string') {\n    const mimeType = ((block.mime_type as string | undefined) ?? '').split(\n      ';'\n    )[0];\n\n    if (sourceType === 'text' && typeof block.text === 'string') {\n      return getTokenCount(block.text as string);\n    }\n\n    if (sourceType === 'base64' && typeof block.data === 'string') {\n      if (mimeType === 'application/pdf' || mimeType === '') {\n        const pageEstimate = Math.max(\n          1,\n          Math.ceil((block.data as string).length / BASE64_BYTES_PER_PDF_PAGE)\n        );\n        return pageEstimate * pdfTokensPerPage;\n      }\n      // Image inside a file block — delegate to image estimation\n      if (mimeType.startsWith('image/')) {\n        return estimateImageBlockTokens(\n          {\n            ...block,\n            type: 'image',\n            source: { type: 'base64', data: block.data },\n          },\n          encoding\n        );\n      }\n      return getTokenCount(block.data as string);\n    }\n\n    if (sourceType === 'url') {\n      return URL_DOCUMENT_FALLBACK_TOKENS;\n    }\n\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  // Anthropic format: type='document', source: { type, data, media_type }\n  const source = block.source as\n    | {\n        type?: string;\n        data?: string;\n        media_type?: string;\n        content?: unknown[];\n      }\n    | undefined;\n\n  if (source == null) {\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  if (source.type === 'text' && typeof source.data === 'string') {\n    return getTokenCount(source.data);\n  }\n\n  if (source.type === 'base64' && typeof source.data === 'string') {\n    const mediaType = (source.media_type ?? '').split(';')[0];\n    if (mediaType === 'application/pdf' || mediaType === '') {\n      const pageEstimate = Math.max(\n        1,\n        Math.ceil(source.data.length / BASE64_BYTES_PER_PDF_PAGE)\n      );\n      return pageEstimate * pdfTokensPerPage;\n    }\n    if (mediaType.startsWith('image/')) {\n      return estimateImageBlockTokens(\n        { type: 'image', source: { type: 'base64', data: source.data } },\n        encoding\n      );\n    }\n    return getTokenCount(source.data);\n  }\n\n  if (source.type === 'url') {\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  // content-type source (wraps other blocks like images)\n  if (source.type === 'content' && Array.isArray(source.content)) {\n    let total = 0;\n    for (const inner of source.content) {\n      if (inner != null && typeof inner === 'object' && 'type' in inner) {\n        const innerBlock = inner as Record<string, unknown>;\n        if (innerBlock.type === 'image') {\n          total += estimateImageBlockTokens(innerBlock, encoding);\n        }\n      }\n    }\n    return total > 0 ? total : URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  return URL_DOCUMENT_FALLBACK_TOKENS;\n}\n\nconst tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};\n\nasync function getTokenizer(\n  encoding: EncodingName = 'o200k_base'\n): Promise<Tokenizer> {\n  const cached = tokenizers[encoding];\n  if (cached) {\n    return cached;\n  }\n  const data =\n    encoding === 'claude'\n      ? await import('ai-tokenizer/encoding/claude')\n      : await import('ai-tokenizer/encoding/o200k_base');\n  const instance = new Tokenizer(data);\n  tokenizers[encoding] = instance;\n  return instance;\n}\n\nexport function encodingForModel(model: string): EncodingName {\n  if (model.toLowerCase().includes('claude')) {\n    return 'claude';\n  }\n  return 'o200k_base';\n}\n\nexport function getTokenCountForMessage(\n  message: BaseMessage,\n  getTokenCount: (text: string) => number,\n  encoding: EncodingName = 'o200k_base'\n): number {\n  const tokensPerMessage = 3;\n\n  type ContentBlock = Record<string, unknown> & {\n    type?: string;\n    tool_call?: { name?: string; args?: string; output?: string };\n  };\n\n  const processValue = (value: unknown): void => {\n    if (Array.isArray(value)) {\n      for (const raw of value) {\n        const item = raw as ContentBlock | null | undefined;\n        if (item == null || typeof item.type !== 'string') {\n          continue;\n        }\n        if (item.type === ContentTypes.ERROR) {\n          continue;\n        }\n\n        if (\n          item.type === ContentTypes.IMAGE_URL ||\n          item.type === 'image_url' ||\n          item.type === 'image'\n        ) {\n          numTokens += Math.ceil(\n            estimateImageBlockTokens(item, encoding) * IMAGE_TOKEN_SAFETY_MARGIN\n          );\n          continue;\n        }\n\n        if (\n          item.type === 'document' ||\n          item.type === 'file' ||\n          item.type === ContentTypes.IMAGE_FILE\n        ) {\n          numTokens += Math.ceil(\n            estimateDocumentBlockTokens(item, encoding, getTokenCount) *\n              IMAGE_TOKEN_SAFETY_MARGIN\n          );\n          continue;\n        }\n\n        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {\n          const toolName = item.tool_call.name;\n          if (typeof toolName === 'string' && toolName.length > 0) {\n            numTokens += getTokenCount(toolName);\n          }\n          const args = item.tool_call.args;\n          if (typeof args === 'string' && args.length > 0) {\n            numTokens += getTokenCount(args);\n          }\n          const output = item.tool_call.output;\n          if (typeof output === 'string' && output.length > 0) {\n            numTokens += getTokenCount(output);\n          }\n          continue;\n        }\n\n        const nestedValue = item[item.type];\n        if (nestedValue == null) {\n          continue;\n        }\n\n        processValue(nestedValue);\n      }\n    } else if (typeof value === 'string') {\n      numTokens += getTokenCount(value);\n    } else if (typeof value === 'number') {\n      numTokens += getTokenCount(value.toString());\n    } else if (typeof value === 'boolean') {\n      numTokens += getTokenCount(value.toString());\n    }\n  };\n\n  let numTokens = tokensPerMessage;\n  processValue(message.content);\n  return numTokens;\n}\n\n/**\n * Anthropic's API consistently reports ~10% more tokens than the local\n * claude tokenizer due to internal message framing and content encoding.\n * Verified empirically across content types via the count_tokens endpoint.\n */\nconst CLAUDE_TOKEN_CORRECTION = 1.1;\n\n/**\n * Creates a token counter function using the specified encoding.\n * Lazily loads the encoding data on first use via dynamic import.\n */\nexport const createTokenCounter = async (\n  encoding: EncodingName = 'o200k_base'\n): Promise<(message: BaseMessage) => number> => {\n  const tok = await getTokenizer(encoding);\n  const countTokens = (text: string): number => tok.count(text);\n  const isClaude = encoding === 'claude';\n  return (message: BaseMessage): number => {\n    const count = getTokenCountForMessage(message, countTokens, encoding);\n    return isClaude ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION) : count;\n  };\n};\n\n/** Utility to manage the token encoder lifecycle explicitly. */\nexport const TokenEncoderManager = {\n  async initialize(): Promise<void> {\n    // No-op: ai-tokenizer is synchronously initialized from bundled data.\n  },\n\n  reset(): void {\n    for (const key of Object.keys(tokenizers)) {\n      delete tokenizers[key as EncodingName];\n    }\n  },\n\n  isInitialized(): boolean {\n    return Object.keys(tokenizers).length > 0;\n  },\n};\n"],"mappings":"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"}
+{"version":3,"file":"tokens.mjs","names":[],"sources":["../../../src/utils/tokens.ts"],"sourcesContent":["import { Tokenizer } from 'ai-tokenizer';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { ContentTypes } from '@/common/enum';\n\nexport type EncodingName = 'o200k_base' | 'claude';\n\n/** Anthropic minimum image token cost. */\nconst ANTHROPIC_IMAGE_MIN_TOKENS = 1024;\n/** Anthropic divisor: tokens = width × height / 750. */\nconst ANTHROPIC_IMAGE_DIVISOR = 750;\n/** OpenAI low-detail fixed cost. */\nconst OPENAI_IMAGE_LOW_TOKENS = 85;\n/** OpenAI high-detail tile size. */\nconst OPENAI_IMAGE_TILE_SIZE = 512;\n/** OpenAI high-detail tokens per tile. */\nconst OPENAI_IMAGE_TOKENS_PER_TILE = 170;\n/** Google Gemini fixed per-image cost. */\nconst _GEMINI_IMAGE_TOKENS = 258;\n/** Safety margin for image and document token estimates (5% overestimate). */\nconst IMAGE_TOKEN_SAFETY_MARGIN = 1.05;\n\n/**\n * Anthropic PDF: each page costs image tokens + text tokens.\n * Typical range is 1500-3000 tokens/page. Using 2000 as midpoint.\n */\nconst ANTHROPIC_PDF_TOKENS_PER_PAGE = 2000;\n/** OpenAI PDF: each page rendered as high-detail image. ~1500 tokens typical. */\nconst OPENAI_PDF_TOKENS_PER_PAGE = 1500;\n/** Gemini PDF: fixed 258 tokens per page. */\nconst _GEMINI_PDF_TOKENS_PER_PAGE = 258;\n/** Approximate base64 bytes per PDF page for page count estimation. */\nconst BASE64_BYTES_PER_PDF_PAGE = 75_000;\n/** Fallback token cost for URL-referenced documents without local data. */\nconst URL_DOCUMENT_FALLBACK_TOKENS = 2000;\n\n/**\n * Extracts image dimensions from the first bytes of a base64-encoded\n * PNG, JPEG, GIF, or WebP without decoding the full image.\n * Returns null if the format is unrecognized or data is too short.\n */\nexport function extractImageDimensions(\n  base64Data: string\n): { width: number; height: number } | null {\n  const raw = base64Data.startsWith('data:')\n    ? base64Data.slice(base64Data.indexOf(',') + 1)\n    : base64Data;\n\n  if (raw.length < 32) {\n    return null;\n  }\n\n  const bytes = new Uint8Array(Buffer.from(raw.slice(0, 80), 'base64'));\n\n  if (bytes[0] === 0x89 && bytes[1] === 0x50) {\n    // PNG: width at bytes 16-19, height at 20-23 (big-endian)\n    const width =\n      (bytes[16] << 24) | (bytes[17] << 16) | (bytes[18] << 8) | bytes[19];\n    const height =\n      (bytes[20] << 24) | (bytes[21] << 16) | (bytes[22] << 8) | bytes[23];\n    return { width, height };\n  }\n\n  if (bytes[0] === 0xff && bytes[1] === 0xd8) {\n    // JPEG: scan for SOF0 (0xFFC0) or SOF2 (0xFFC2) marker\n    for (let i = 2; i < bytes.length - 9; i++) {\n      if (\n        bytes[i] === 0xff &&\n        (bytes[i + 1] === 0xc0 || bytes[i + 1] === 0xc2)\n      ) {\n        const height = (bytes[i + 5] << 8) | bytes[i + 6];\n        const width = (bytes[i + 7] << 8) | bytes[i + 8];\n        return { width, height };\n      }\n    }\n    return null;\n  }\n\n  if (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {\n    // GIF: width at bytes 6-7, height at 8-9 (little-endian)\n    const width = bytes[6] | (bytes[7] << 8);\n    const height = bytes[8] | (bytes[9] << 8);\n    return { width, height };\n  }\n\n  if (\n    bytes[0] === 0x52 &&\n    bytes[1] === 0x49 &&\n    bytes[2] === 0x46 &&\n    bytes[3] === 0x46 &&\n    bytes[8] === 0x57 &&\n    bytes[9] === 0x45 &&\n    bytes[10] === 0x42 &&\n    bytes[11] === 0x50\n  ) {\n    // WebP VP8: width at bytes 26-27, height at 28-29\n    if (bytes.length > 29) {\n      const width = (bytes[26] | (bytes[27] << 8)) & 0x3fff;\n      const height = (bytes[28] | (bytes[29] << 8)) & 0x3fff;\n      return { width, height };\n    }\n    return null;\n  }\n\n  return null;\n}\n\n/** Estimates image token cost for Anthropic/Bedrock (Claude). */\nexport function estimateAnthropicImageTokens(\n  width: number,\n  height: number\n): number {\n  return Math.max(\n    ANTHROPIC_IMAGE_MIN_TOKENS,\n    Math.ceil((width * height) / ANTHROPIC_IMAGE_DIVISOR)\n  );\n}\n\n/** Estimates image token cost for OpenAI (high detail). */\nexport function estimateOpenAIImageTokens(\n  width: number,\n  height: number,\n  detail: string = 'high'\n): number {\n  if (detail === 'low') {\n    return OPENAI_IMAGE_LOW_TOKENS;\n  }\n  const tiles =\n    Math.ceil(width / OPENAI_IMAGE_TILE_SIZE) *\n    Math.ceil(height / OPENAI_IMAGE_TILE_SIZE);\n  return OPENAI_IMAGE_LOW_TOKENS + tiles * OPENAI_IMAGE_TOKENS_PER_TILE;\n}\n\n/**\n * Estimates token cost for an image content block.\n * Extracts dimensions from base64 header when available.\n * Falls back to Anthropic minimum (1024) when dimensions can't be determined.\n */\nfunction estimateImageBlockTokens(\n  block: Record<string, unknown>,\n  encoding: EncodingName\n): number {\n  let base64Data: string | undefined;\n\n  if (block.type === ContentTypes.IMAGE_URL || block.type === 'image_url') {\n    const imageUrl = block.image_url as string | { url?: string } | undefined;\n    const url = typeof imageUrl === 'string' ? imageUrl : imageUrl?.url;\n    if (typeof url === 'string' && url.startsWith('data:')) {\n      base64Data = url;\n    } else {\n      return ANTHROPIC_IMAGE_MIN_TOKENS;\n    }\n  } else if (block.type === 'image') {\n    const source = block.source as { type?: string; data?: string } | undefined;\n    if (source?.type === 'base64' && typeof source.data === 'string') {\n      base64Data = source.data;\n    } else {\n      return ANTHROPIC_IMAGE_MIN_TOKENS;\n    }\n  } else {\n    return ANTHROPIC_IMAGE_MIN_TOKENS;\n  }\n\n  const dims = extractImageDimensions(base64Data);\n  if (dims == null) {\n    return ANTHROPIC_IMAGE_MIN_TOKENS;\n  }\n\n  if (encoding === 'claude') {\n    return estimateAnthropicImageTokens(dims.width, dims.height);\n  }\n  return estimateOpenAIImageTokens(dims.width, dims.height);\n}\n\n/**\n * Estimates token cost for a document/file content block.\n * Handles both LangChain standard format (`type: 'file'` with `source_type`)\n * and Anthropic format (`type: 'document'` with `source`).\n *\n * - Plain text: tokenized directly via `getTokenCount`.\n * - Base64 PDF: page count estimated from base64 length × per-page cost.\n * - URL reference: conservative flat estimate.\n */\nfunction estimateDocumentBlockTokens(\n  block: Record<string, unknown>,\n  encoding: EncodingName,\n  getTokenCount: (text: string) => number\n): number {\n  const pdfTokensPerPage =\n    encoding === 'claude'\n      ? ANTHROPIC_PDF_TOKENS_PER_PAGE\n      : OPENAI_PDF_TOKENS_PER_PAGE;\n\n  // LangChain standard format: type='file', source_type, data/text/url, mime_type\n  const sourceType = block.source_type as string | undefined;\n  if (typeof sourceType === 'string') {\n    const mimeType = ((block.mime_type as string | undefined) ?? '').split(\n      ';'\n    )[0];\n\n    if (sourceType === 'text' && typeof block.text === 'string') {\n      return getTokenCount(block.text as string);\n    }\n\n    if (sourceType === 'base64' && typeof block.data === 'string') {\n      if (mimeType === 'application/pdf' || mimeType === '') {\n        const pageEstimate = Math.max(\n          1,\n          Math.ceil((block.data as string).length / BASE64_BYTES_PER_PDF_PAGE)\n        );\n        return pageEstimate * pdfTokensPerPage;\n      }\n      // Image inside a file block — delegate to image estimation\n      if (mimeType.startsWith('image/')) {\n        return estimateImageBlockTokens(\n          {\n            ...block,\n            type: 'image',\n            source: { type: 'base64', data: block.data },\n          },\n          encoding\n        );\n      }\n      return getTokenCount(block.data as string);\n    }\n\n    if (sourceType === 'url') {\n      return URL_DOCUMENT_FALLBACK_TOKENS;\n    }\n\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  // Anthropic format: type='document', source: { type, data, media_type }\n  const source = block.source as\n    | {\n        type?: string;\n        data?: string;\n        media_type?: string;\n        content?: unknown[];\n      }\n    | undefined;\n\n  if (source == null) {\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  if (source.type === 'text' && typeof source.data === 'string') {\n    return getTokenCount(source.data);\n  }\n\n  if (source.type === 'base64' && typeof source.data === 'string') {\n    const mediaType = (source.media_type ?? '').split(';')[0];\n    if (mediaType === 'application/pdf' || mediaType === '') {\n      const pageEstimate = Math.max(\n        1,\n        Math.ceil(source.data.length / BASE64_BYTES_PER_PDF_PAGE)\n      );\n      return pageEstimate * pdfTokensPerPage;\n    }\n    if (mediaType.startsWith('image/')) {\n      return estimateImageBlockTokens(\n        { type: 'image', source: { type: 'base64', data: source.data } },\n        encoding\n      );\n    }\n    return getTokenCount(source.data);\n  }\n\n  if (source.type === 'url') {\n    return URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  // content-type source (wraps other blocks like images)\n  if (source.type === 'content' && Array.isArray(source.content)) {\n    let total = 0;\n    for (const inner of source.content) {\n      if (inner != null && typeof inner === 'object' && 'type' in inner) {\n        const innerBlock = inner as Record<string, unknown>;\n        if (innerBlock.type === 'image') {\n          total += estimateImageBlockTokens(innerBlock, encoding);\n        }\n      }\n    }\n    return total > 0 ? total : URL_DOCUMENT_FALLBACK_TOKENS;\n  }\n\n  return URL_DOCUMENT_FALLBACK_TOKENS;\n}\n\nconst tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};\n\nasync function getTokenizer(\n  encoding: EncodingName = 'o200k_base'\n): Promise<Tokenizer> {\n  const cached = tokenizers[encoding];\n  if (cached) {\n    return cached;\n  }\n  const data =\n    encoding === 'claude'\n      ? await import('ai-tokenizer/encoding/claude')\n      : await import('ai-tokenizer/encoding/o200k_base');\n  const instance = new Tokenizer(data);\n  tokenizers[encoding] = instance;\n  return instance;\n}\n\nexport function encodingForModel(model: string): EncodingName {\n  if (model.toLowerCase().includes('claude')) {\n    return 'claude';\n  }\n  return 'o200k_base';\n}\n\nexport function getTokenCountForMessage(\n  message: BaseMessage,\n  getTokenCount: (text: string) => number,\n  encoding: EncodingName = 'o200k_base'\n): number {\n  const tokensPerMessage = 3;\n\n  type ContentBlock = Record<string, unknown> & {\n    type?: string;\n    tool_call?: { name?: string; args?: string; output?: string };\n  };\n\n  const processValue = (value: unknown): void => {\n    if (Array.isArray(value)) {\n      for (const raw of value) {\n        const item = raw as ContentBlock | null | undefined;\n        if (item == null || typeof item.type !== 'string') {\n          continue;\n        }\n        if (item.type === ContentTypes.ERROR) {\n          continue;\n        }\n\n        if (\n          item.type === ContentTypes.IMAGE_URL ||\n          item.type === 'image_url' ||\n          item.type === 'image'\n        ) {\n          numTokens += Math.ceil(\n            estimateImageBlockTokens(item, encoding) * IMAGE_TOKEN_SAFETY_MARGIN\n          );\n          continue;\n        }\n\n        if (\n          item.type === 'document' ||\n          item.type === 'file' ||\n          item.type === ContentTypes.IMAGE_FILE\n        ) {\n          numTokens += Math.ceil(\n            estimateDocumentBlockTokens(item, encoding, getTokenCount) *\n              IMAGE_TOKEN_SAFETY_MARGIN\n          );\n          continue;\n        }\n\n        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {\n          const toolName = item.tool_call.name;\n          if (typeof toolName === 'string' && toolName.length > 0) {\n            numTokens += getTokenCount(toolName);\n          }\n          const args = item.tool_call.args;\n          if (typeof args === 'string' && args.length > 0) {\n            numTokens += getTokenCount(args);\n          }\n          const output = item.tool_call.output;\n          if (typeof output === 'string' && output.length > 0) {\n            numTokens += getTokenCount(output);\n          }\n          continue;\n        }\n\n        const nestedValue = item[item.type];\n        if (nestedValue == null) {\n          continue;\n        }\n\n        processValue(nestedValue);\n      }\n    } else if (typeof value === 'string') {\n      numTokens += getTokenCount(value);\n    } else if (typeof value === 'number') {\n      numTokens += getTokenCount(value.toString());\n    } else if (typeof value === 'boolean') {\n      numTokens += getTokenCount(value.toString());\n    }\n  };\n\n  let numTokens = tokensPerMessage;\n  processValue(message.content);\n  return numTokens;\n}\n\n/**\n * Largest-remainder apportionment: scales each count by `multiplier` and\n * distributes the rounding remainder so the results sum exactly to\n * `targetTotal`. Keeps per-item breakdowns reconciled with an aggregate\n * computed as a single rounded product of the summed raw counts.\n */\nexport function apportionTokenCounts(\n  rawCounts: Record<string, number>,\n  multiplier: number,\n  targetTotal: number\n): Record<string, number> {\n  const result: Record<string, number> = Object.create(null);\n  const remainders: Array<{ name: string; remainder: number }> = [];\n  let floorSum = 0;\n  for (const [name, rawCount] of Object.entries(rawCounts)) {\n    const scaled = rawCount * multiplier;\n    const floored = Math.floor(scaled);\n    result[name] = floored;\n    floorSum += floored;\n    remainders.push({ name, remainder: scaled - floored });\n  }\n  let leftover = targetTotal - floorSum;\n  if (leftover <= 0 || remainders.length === 0) {\n    return result;\n  }\n  remainders.sort((a, b) => b.remainder - a.remainder);\n  for (let i = 0; leftover > 0; i = (i + 1) % remainders.length) {\n    result[remainders[i].name] += 1;\n    leftover--;\n  }\n  return result;\n}\n\n/**\n * Anthropic's API consistently reports ~10% more tokens than the local\n * claude tokenizer due to internal message framing and content encoding.\n * Verified empirically across content types via the count_tokens endpoint.\n */\nconst CLAUDE_TOKEN_CORRECTION = 1.1;\n\n/**\n * Creates a token counter function using the specified encoding.\n * Lazily loads the encoding data on first use via dynamic import.\n */\nexport const createTokenCounter = async (\n  encoding: EncodingName = 'o200k_base'\n): Promise<(message: BaseMessage) => number> => {\n  const tok = await getTokenizer(encoding);\n  const countTokens = (text: string): number => tok.count(text);\n  const isClaude = encoding === 'claude';\n  return (message: BaseMessage): number => {\n    const count = getTokenCountForMessage(message, countTokens, encoding);\n    return isClaude ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION) : count;\n  };\n};\n\n/** Utility to manage the token encoder lifecycle explicitly. */\nexport const TokenEncoderManager = {\n  async initialize(): Promise<void> {\n    // No-op: ai-tokenizer is synchronously initialized from bundled data.\n  },\n\n  reset(): void {\n    for (const key of Object.keys(tokenizers)) {\n      delete tokenizers[key as EncodingName];\n    }\n  },\n\n  isInitialized(): boolean {\n    return Object.keys(tokenizers).length > 0;\n  },\n};\n"],"mappings":"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"}

package/dist/types/agents/AgentContext.d.ts

@@ -60,6 +60,11 @@ export declare class AgentContext {
     dynamicInstructionTokens: number;
     /** Token count for tool schemas only. */
     toolSchemaTokens: number;
+    /** Per-tool schema token counts (post-multiplier), keyed by tool name.
+     *  `undefined` when not calculated (e.g. cached aggregate schema tokens). */
+    toolTokenCounts?: Record<string, number>;
+    /** Names of counted tools that are deferred (`defer_loading`) and discovered. */
+    deferredToolNames: string[];
     /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
     calibrationRatio: number;
     /** Provider-observed instruction overhead from the pruner's best-variance turn. */
@@ -330,9 +335,8 @@ export declare class AgentContext {
      * Returns a structured breakdown of how the context token budget is consumed.
      * Useful for diagnostics when context overflow or pruning issues occur.
      *
-     * Note: `toolCount` reflects discoveries immediately, but `toolSchemaTokens`
-     * is a snapshot taken during `calculateInstructionTokens` and is not
-     * recomputed when `markToolsAsDiscovered` is called mid-run.
+     * Note: `markToolsAsDiscovered` re-triggers `calculateInstructionTokens`,
+     * so `toolSchemaTokens`/`toolTokenCounts` refresh before the next call.
      */
     getTokenBudgetBreakdown(messages?: BaseMessage[]): t.TokenBudgetBreakdown;
     /**

package/dist/types/common/enum.d.ts

@@ -29,6 +29,8 @@ export declare enum GraphEvents {
     ON_SUBAGENT_UPDATE = "on_subagent_update",
     /** [Custom] Diagnostic logging event for context management observability */
     ON_AGENT_LOG = "on_agent_log",
+    /** [Custom] Per-model-call context window usage snapshot (post-prune token budget) */
+    ON_CONTEXT_USAGE = "on_context_usage",
     /** Custom event, emitted by system */
     ON_CUSTOM_EVENT = "on_custom_event",
     /** Emitted when a chat model starts processing. */
@@ -140,6 +142,17 @@ export declare enum Constants {
     /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
     ANTHROPIC_SERVER_TOOL_PREFIX = "srvtoolu_",
     SKILL_TOOL = "skill",
+    /**
+     * Callback-metadata keys stamped by `attemptInvoke` /
+     * `tryFallbackProviders` carrying the provider (SDK `Providers` enum
+     * value) and configured model that actually served a model invocation.
+     * Unlike `ls_provider` — which derived providers inherit from their base
+     * class (e.g. DeepSeek/OpenRouter report `'openai'`) — these reflect the
+     * SDK's own routing, including fallback-provider calls. Consumed by the
+     * subagent usage-capture handler to tag billing events.
+     */
+    INVOKED_PROVIDER = "__invoked_provider",
+    INVOKED_MODEL = "__invoked_model",
     READ_FILE = "read_file",
     BASH_TOOL = "bash_tool",
     BASH_PROGRAMMATIC_TOOL_CALLING = "run_tools_with_bash",

package/dist/types/graphs/Graph.d.ts

@@ -179,7 +179,14 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     agentContexts: Map<string, AgentContext>;
     /** Default agent ID to use */
     defaultAgentId: string;
-    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, }: t.StandardGraphInput);
+    /**
+     * Host sink for model usage emitted inside subagent child runs. Threaded
+     * into each `SubagentExecutor` this graph creates (and from there into
+     * child graphs, so nested subagents report too). See
+     * {@link t.StandardGraphInput.subagentUsageSink}.
+     */
+    subagentUsageSink?: t.SubagentUsageSink;
+    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, }: t.StandardGraphInput);
     resetValues(keepContent?: boolean): void;
     clearHeavyState(): void;
     getRunStep(stepId: string): t.RunStep | undefined;

package/dist/types/llm/bedrock/utils/index.d.ts

@@ -2,4 +2,4 @@
  * Bedrock Converse utility exports.
  */
 export { convertToConverseMessages, extractImageInfo, langchainReasoningBlockToBedrockReasoningBlock, concatenateLangchainReasoningBlocks, } from './message_inputs';
-export { convertConverseMessageToLangChainMessage, handleConverseStreamContentBlockStart, handleConverseStreamContentBlockDelta, handleConverseStreamMetadata, bedrockReasoningBlockToLangchainReasoningBlock, bedrockReasoningDeltaToLangchainPartialReasoningBlock, } from './message_outputs';
+export { convertConverseMessageToLangChainMessage, createConverseToolUseStopChunk, handleConverseStreamContentBlockStart, handleConverseStreamContentBlockDelta, handleConverseStreamMetadata, bedrockReasoningBlockToLangchainReasoningBlock, bedrockReasoningDeltaToLangchainPartialReasoningBlock, } from './message_outputs';

package/dist/types/llm/bedrock/utils/message_outputs.d.ts

@@ -25,6 +25,15 @@ export declare function handleConverseStreamContentBlockDelta(contentBlockDelta:
  * Handle a content block start event from Bedrock Converse stream.
  */
 export declare function handleConverseStreamContentBlockStart(contentBlockStart: ContentBlockStartEvent): ChatGenerationChunk | null;
+/**
+ * Build the chunk emitted when a Converse `contentBlockStop` event closes a
+ * toolUse block. The Converse protocol guarantees a block's input is complete
+ * at `contentBlockStop`, so this chunk carries an explicit streamed tool-call
+ * seal for that block index. The empty `args` delta merges as a no-op into the
+ * accumulated tool call; id/name are omitted so the chunk matches the existing
+ * entry purely by index.
+ */
+export declare function createConverseToolUseStopChunk(contentBlockIndex: number): ChatGenerationChunk;
 /**
  * Handle a metadata event from Bedrock Converse stream.
  */

package/dist/types/llm/invoke.d.ts

@@ -3,8 +3,8 @@ import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
-import { ChatModelStreamHandler } from '@/stream';
 import { Providers } from '@/common';
+import { ChatModelStreamHandler } from '@/stream';
 /**
  * Context passed to `attemptInvoke`. Matches the subset of Graph that
  * `ChatModelStreamHandler.handle` needs *plus* the explicit

package/dist/types/llm/vertexai/index.d.ts

@@ -1,4 +1,5 @@
 import { ChatGoogle } from '@langchain/google-gauth';
+import { AIMessageChunk } from '@langchain/core/messages';
 import type { GeminiContent, GoogleAIModelRequestParams, GoogleAbstractedClient } from '@langchain/google-common';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
@@ -29,6 +30,15 @@ import type { GoogleThinkingConfig, VertexAIClientOptions } from '@/types';
  * overriding `_convertToUsageMetadata`.
  */
 export declare function repairStreamUsageMetadata(current: UsageMetadata | undefined, generationInfoUsage: UsageMetadata | undefined): UsageMetadata | undefined;
+/**
+ * The Gemini API delivers function calls as complete objects — never as
+ * partial arg deltas. `@langchain/google-common` pre-parses each streamed
+ * functionCall part into `tool_calls` (invalid args land in
+ * `invalid_tool_calls` instead), so a chunk whose tool-call chunks all parsed
+ * cleanly is sealed on arrival for eager tool execution. Anything that fails
+ * the parse check is left unstamped and falls back to the lazy path.
+ */
+export declare function sealCompleteStreamedToolCalls(message: AIMessageChunk): void;
 /**
  * Fixes thought signatures on functionCall parts in the formatted Gemini request.
  *

package/dist/types/messages/content.d.ts

@@ -1,4 +1,9 @@
 import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Whether {@link formatContentStrings} will flatten this message's content:
+ * a human/ai/system message whose content is an array of text-only blocks.
+ */
+export declare const isLegacyConvertible: (message: BaseMessage) => boolean;
 /**
  * Formats an array of messages for LangChain, making sure all content fields are strings
  * @param {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} payload - The array of messages to format.

package/dist/types/messages/prune.d.ts

@@ -220,4 +220,8 @@ export declare function createPruneMessages(factoryParams: PruneMessagesFactoryP
     originalToolContent?: Map<number, string>;
     calibrationRatio?: number;
     resolvedInstructionOverhead?: number;
+    /** Usable budget this call: maxTokens minus output reserve */
+    contextBudget?: number;
+    /** Calibrated instruction overhead actually applied this call */
+    effectiveInstructionTokens?: number;
 };

package/dist/types/run.d.ts

@@ -15,6 +15,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private toolOutputReferences?;
     private eagerEventToolExecution?;
     private toolExecution?;
+    private subagentUsageSink?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

package/dist/types/tools/ToolNode.d.ts

@@ -350,6 +350,14 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private dispatchPostToolBatchAndInjectContext;
     private dispatchStepCompleted;
+    /**
+     * Emits the completed run step for a single host-reported result before
+     * the batch resolves. Mirrors the batch loop's output formatting exactly;
+     * callers gate on the no-hooks/no-HITL configuration, so the raw result
+     * content here is also the final content. Returns whether the event was
+     * actually dispatched so the caller can fall back to batch-time emission.
+     */
+    private dispatchEarlyToolCompletion;
     /**
      * Converts InjectedMessage instances to LangChain HumanMessage objects.
      * Both 'user' and 'system' roles become HumanMessage to avoid provider

package/dist/types/tools/streamedToolCallSeals.d.ts

@@ -1,7 +1,11 @@
 export declare const STREAMED_TOOL_CALL_ADAPTER_METADATA_KEY = "lc_streamed_tool_call_adapter";
 export declare const STREAMED_TOOL_CALL_SEAL_METADATA_KEY = "lc_streamed_tool_call_seal";
 export declare const OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER = "openai_responses";
-export type StreamedToolCallAdapter = typeof OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER;
+export declare const BEDROCK_CONVERSE_STREAMED_TOOL_CALL_ADAPTER = "bedrock_converse";
+export declare const GOOGLE_STREAMED_TOOL_CALL_ADAPTER = "google_genai";
+export declare const OPENAI_CHAT_SEQUENTIAL_STREAMED_TOOL_CALL_ADAPTER = "openai_chat_sequential";
+export type StreamedToolCallAdapter = typeof OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER | typeof BEDROCK_CONVERSE_STREAMED_TOOL_CALL_ADAPTER | typeof GOOGLE_STREAMED_TOOL_CALL_ADAPTER | typeof OPENAI_CHAT_SEQUENTIAL_STREAMED_TOOL_CALL_ADAPTER;
+export declare function streamedToolCallAdapterAllowsSequentialSeal(metadata: Record<string, unknown> | undefined): boolean;
 export type StreamedToolCallSeal = {
     kind: 'single';
     id?: string;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -1,5 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
-import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
+import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, SubagentUsageSink, TokenCounter } from '@/types';
 import type { HookRegistry } from '@/hooks';
 import type { AgentContext } from '@/agents/AgentContext';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -88,6 +88,15 @@ export type SubagentExecutorOptions = {
      * post-`createWorkflow`, so `createAgentNode` must capture lazily).
      */
     parentHandlerRegistry?: HandlerRegistry | (() => HandlerRegistry | undefined);
+    /**
+     * Receives a usage event for every model call the child run makes. The
+     * child workflow executes via `invoke()` with a detached callbacks array,
+     * so its `on_chat_model_end` events never reach the parent's handler
+     * registry — without this sink, child token usage is invisible to the
+     * host (unbilled model calls). Forwarded into the child graph's input so
+     * nested subagents report through the same sink.
+     */
+    usageSink?: SubagentUsageSink;
 };
 export declare class SubagentExecutor {
     private readonly configs;
@@ -99,6 +108,7 @@ export declare class SubagentExecutor {
     private readonly tokenCounter?;
     private readonly maxDepth;
     private readonly createChildGraph;
+    private readonly usageSink?;
     private readonly resolveParentHandlerRegistry?;
     constructor(options: SubagentExecutorOptions);
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */

package/dist/types/types/graph.d.ts

@@ -1,4 +1,4 @@
-import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core/messages';
+import type { BaseMessage, AIMessageChunk, SystemMessage, UsageMetadata } from '@langchain/core/messages';
 import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
@@ -7,10 +7,10 @@ import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
+import type { TokenCounter, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
-import type { TokenCounter } from '@/types/run';
 /** Interface for bound model with stream and invoke methods */
 export interface ChatModel {
     stream?: (messages: BaseMessage[], config?: RunnableConfig) => Promise<AsyncIterable<AIMessageChunk>>;
@@ -44,8 +44,31 @@ export interface AgentLogEvent {
     runId?: string;
     agentId?: string;
 }
+/**
+ * Per-model-call context window usage snapshot, dispatched after pruning and
+ * before the model invocation. Dispatched once per `callModel` invocation:
+ * fallback retries reuse the snapshot since the prompt is identical — budget
+ * numbers reflect the primary provider's tokenizer, and the calibration
+ * ratio self-corrects from whichever provider reports usage.
+ */
+export interface ContextUsageEvent {
+    runId?: string;
+    agentId?: string;
+    /** Structural token budget snapshot from AgentContext.getTokenBudgetBreakdown */
+    breakdown: TokenBudgetBreakdown;
+    /** Usable budget this call: maxContextTokens minus output reserve */
+    contextBudget?: number;
+    /** Calibrated instruction overhead actually applied this call */
+    effectiveInstructionTokens?: number;
+    /** Calibrated message tokens before pruning (excluding instructions) */
+    prePruneContextTokens?: number;
+    /** Tokens still free after instructions + pruned messages */
+    remainingContextTokens?: number;
+    /** EMA ratio of provider-reported vs locally estimated token counts */
+    calibrationRatio?: number;
+}
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -199,6 +222,17 @@ export type StandardGraphInput = {
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
     calibrationRatio?: number;
+    /**
+     * Receives a {@link SubagentUsageEvent} for every model call made inside
+     * a subagent child run spawned from this graph (including nested
+     * subagents and child-side summarization calls). Child graphs run via
+     * `invoke()` outside the host's `streamEvents` loop, so their
+     * `on_chat_model_end` events never reach the run's handler registry —
+     * this sink is the only way hosts can observe child token usage for
+     * billing/accounting. Parent-graph model calls are NOT reported here;
+     * they already flow through the registry's `CHAT_MODEL_END` handler.
+     */
+    subagentUsageSink?: SubagentUsageSink;
 };
 export type GraphEdge = {
     /** Agent ID, use a list for multiple sources */
@@ -289,6 +323,58 @@ export interface SubagentUpdateEvent {
     /** ISO timestamp for ordering / display. */
     timestamp: string;
 }
+/**
+ * Token usage for a single model call made inside a subagent child run.
+ * Emitted through {@link SubagentUsageSink} as each call completes, so
+ * hosts can bill child-run model usage that never reaches the parent
+ * run's `CHAT_MODEL_END` handler (child graphs execute via `invoke()`
+ * outside the host's `streamEvents` loop).
+ */
+export interface SubagentUsageEvent {
+    /** Usage metadata reported by the child's model call. */
+    usage: UsageMetadata;
+    /**
+     * Model that produced this usage. Per-call `ls_model_name` from the
+     * model's callback metadata when available (covers child-side
+     * summarization or any call that differs from the configured model),
+     * then the fallback-invocation's configured model (`INVOKED_MODEL`
+     * metadata), then the subagent config's `clientOptions` model.
+     */
+    model?: string;
+    /**
+     * Provider that actually served this call — the SDK `Providers` enum
+     * value stamped per-invocation by `attemptInvoke` (`INVOKED_PROVIDER`
+     * metadata), so fallback-served calls are attributed to the fallback
+     * provider, not the configured primary. Falls back to the subagent
+     * config's provider. Never LangSmith's `ls_provider` string — derived
+     * providers inherit that from their base class, and hosts key
+     * pricing/cache semantics off the enum.
+     */
+    provider?: string;
+    /** Subagent `type` identifier from the SubagentConfig. */
+    subagentType: string;
+    /** Child run ID (unique per subagent execution). */
+    subagentRunId: string;
+    /** Child agent ID assigned to this subagent execution. */
+    subagentAgentId: string;
+    /**
+     * ROOT run ID of the host run that owns billing. For nested subagents
+     * each forwarding layer rewrites this upward, so events from any depth
+     * surface with the outermost run's ID — never an intermediate
+     * `*_sub_*` child id (use {@link subagentRunId} to identify the
+     * emitting child).
+     */
+    runId: string;
+}
+/**
+ * Host-provided callback receiving {@link SubagentUsageEvent}s. Invoked as
+ * each child model call completes. May return a promise — the executor
+ * awaits each dispatch (so all usage is recorded before the child's result
+ * resolves to the parent) and swallows both synchronous throws and
+ * rejections; implementations should still be cheap, as they sit on the
+ * child's model-call path.
+ */
+export type SubagentUsageSink = (event: SubagentUsageEvent) => void | Promise<void>;
 export type LangfuseToolOutputTracingConfig = {
     /**
      * Whether tool outputs should be exported to Langfuse. Defaults to

package/dist/types/types/run.d.ts

@@ -111,6 +111,15 @@ export type RunConfig = {
      */
     langfuse?: g.LangfuseConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /**
+     * Receives token usage for every model call made inside subagent child
+     * runs (including nested subagents). Child graphs execute via `invoke()`
+     * outside this run's `streamEvents` loop, so their model-end events never
+     * reach `customHandlers` — without this sink, child usage is invisible to
+     * the host. Parent-graph calls are not reported here; they flow through
+     * the registered `CHAT_MODEL_END` handler as usual.
+     */
+    subagentUsageSink?: g.SubagentUsageSink;
     /**
      * Pre-constructed hook registry for this run. Hooks fire at lifecycle
      * points in `processStream` (RunStart, UserPromptSubmit, Stop,
@@ -225,6 +234,10 @@ export type TokenBudgetBreakdown = {
     messageTokens: number;
     /** Tokens available for messages after instructions. */
     availableForMessages: number;
+    /** Per-tool schema token counts (post-multiplier), keyed by tool name. */
+    toolTokenCounts?: Record<string, number>;
+    /** Names of counted tools that are deferred (`defer_loading`) and discovered. */
+    deferredToolNames?: string[];
 };
 export type EventStreamOptions = {
     callbacks?: g.ClientCallbacks;

package/dist/types/types/tools.d.ts

@@ -382,6 +382,16 @@ export type ToolExecuteBatchRequest = {
     resolve: (results: ToolExecuteResult[]) => void;
     /** Promise rejector - handler calls this on fatal error */
     reject: (error: Error) => void;
+    /**
+     * Optional per-call result channel. When present, the handler MAY invoke
+     * this as each tool call settles (before the final `resolve`) so the
+     * graph can emit that call's completion event without waiting for the
+     * slowest call in the batch. Purely an emission fast-path: the handler
+     * must still pass every result to `resolve`, which remains the
+     * authoritative batch outcome. Only provided when no post-tool hooks or
+     * human-in-the-loop flows could change a result after execution.
+     */
+    onResult?: (result: ToolExecuteResult) => void;
 };
 /**
  * A message injected into graph state by any tool execution handler.

package/dist/types/utils/tokens.d.ts

@@ -15,6 +15,13 @@ export declare function estimateAnthropicImageTokens(width: number, height: numb
 export declare function estimateOpenAIImageTokens(width: number, height: number, detail?: string): number;
 export declare function encodingForModel(model: string): EncodingName;
 export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number, encoding?: EncodingName): number;
+/**
+ * Largest-remainder apportionment: scales each count by `multiplier` and
+ * distributes the rounding remainder so the results sum exactly to
+ * `targetTotal`. Keeps per-item breakdowns reconciled with an aggregate
+ * computed as a single rounded product of the summed raw counts.
+ */
+export declare function apportionTokenCounts(rawCounts: Record<string, number>, multiplier: number, targetTotal: number): Record<string, number>;
 /**
  * Creates a token counter function using the specified encoding.
  * Lazily loads the encoding data on first use via dynamic import.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.2.33",
+  "version": "3.2.35",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",