@librechat/agents 3.2.34 → 3.2.36

package/src/tools/search/format.ts

@@ -1,6 +1,113 @@
 import type * as t from './types';
 import { getDomainName, fileExtRegex } from './utils';
 
+/** Default per-search budget for model-facing highlight content (chars). Hosts
+ *  that know the context window (e.g. LibreChat) pass a window-relative value;
+ *  this fixed fallback keeps standalone consumers bounded instead of dumping the
+ *  full reranked content of every source into the prompt. */
+const DEFAULT_MAX_LLM_OUTPUT_CHARS = 50000;
+
+/** Minimum room (chars) worth filling with a truncated boundary highlight; below
+ *  this we drop it whole rather than emit a useless sliver. */
+const MIN_PARTIAL_HIGHLIGHT_CHARS = 200;
+
+/** Resolves the per-search highlight budget from config, the
+ *  `SEARCH_MAX_LLM_OUTPUT_CHARS` env var, or the default (50,000 chars). */
+export function resolveMaxLLMOutputChars(maxOutputChars?: number): number {
+  if (maxOutputChars != null && maxOutputChars > 0) {
+    return maxOutputChars;
+  }
+  const envValue = Number(process.env.SEARCH_MAX_LLM_OUTPUT_CHARS);
+  if (Number.isFinite(envValue) && envValue > 0) {
+    return envValue;
+  }
+  return DEFAULT_MAX_LLM_OUTPUT_CHARS;
+}
+
+/** Inline citation markers embedded in highlight text, e.g. `(link#2 "Title")`.
+ *  Mirrors the matcher in `highlights.ts` so truncation can tell which citations
+ *  survive in a sliced prefix. */
+const REFERENCE_MARKER_REGEX = /\((link|image|video)#(\d+)(?:\s+"[^"]*")?\)/g;
+
+/** Builds the set of `type#originalIndex` keys whose complete citation marker
+ *  appears in `text`, so references can be filtered to those still visible. */
+function visibleReferenceKeys(text: string): Set<string> {
+  const keys = new Set<string>();
+  if (!text.includes('#')) {
+    return keys;
+  }
+  const regex = new RegExp(REFERENCE_MARKER_REGEX);
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(text)) !== null) {
+    keys.add(`${match[1]}#${parseInt(match[2], 10) - 1}`);
+  }
+  return keys;
+}
+
+/** Truncates a highlight to `maxLen` chars of (already-trimmed) text, keeping
+ *  only the references whose markers survive in the kept prefix — markers in the
+ *  cut tail would otherwise emit Core References for citations the model can no
+ *  longer see, while a blanket drop would lose still-visible ones. */
+function truncateHighlight(highlight: t.Highlight, text: string, maxLen: number): t.Highlight {
+  const prefix = text.slice(0, maxLen);
+  const truncated: t.Highlight = { score: highlight.score, text: `${prefix}\n…[truncated]` };
+  if (highlight.references != null && highlight.references.length > 0) {
+    const keys = visibleReferenceKeys(prefix);
+    const visible = highlight.references.filter((ref) => keys.has(`${ref.type}#${ref.originalIndex}`));
+    if (visible.length > 0) {
+      truncated.references = visible;
+    }
+  }
+  return truncated;
+}
+
+/** Bounds the highlight chunks — the dominant, unbounded part of search output —
+ *  to `maxChars`, walking sources in relevance order (organic first, then news;
+ *  highlights in their reranked order). Whole highlights are kept until the
+ *  budget is hit, the boundary one is truncated if meaningful room remains, and
+ *  every later highlight is dropped (relevance-ordered prefix). Blank highlights
+ *  are skipped (never rendered, so never charged); a truncated highlight keeps
+ *  only references whose markers survive in the kept prefix. Snippets/titles/URLs
+ *  are left untouched (small, high-signal) and per-source `content` stays in the
+ *  `WEB_SEARCH` artifact for citations. Mutates `results` in place; returns how
+ *  many highlights were dropped or truncated (0 when everything fit). */
+function trimHighlightsToBudget(results: t.SearchResultData, maxChars: number): number {
+  let used = 0;
+  let trimmed = 0;
+  const sections: (t.ValidSource[] | undefined)[] = [results.organic, results.topStories];
+  for (const sources of sections) {
+    if (sources == null) {
+      continue;
+    }
+    for (const source of sources) {
+      const highlights = source.highlights;
+      if (highlights == null || highlights.length === 0) {
+        continue;
+      }
+      const kept: t.Highlight[] = [];
+      for (const highlight of highlights) {
+        const text = highlight.text.trim();
+        if (text.length === 0) {
+          continue;
+        }
+        if (used + text.length <= maxChars) {
+          kept.push(highlight);
+          used += text.length;
+          continue;
+        }
+        const remaining = maxChars - used;
+        if (remaining >= MIN_PARTIAL_HIGHLIGHT_CHARS) {
+          kept.push(truncateHighlight(highlight, text, remaining));
+        }
+        used = maxChars;
+        trimmed++;
+      }
+      source.highlights = kept;
+    }
+  }
+  return trimmed;
+}
+
 function addHighlightSection(): string[] {
   return ['\n## Highlights', ''];
 }
@@ -112,8 +219,15 @@ function formatSource(
 
 export function formatResultsForLLM(
   turn: number,
-  results: t.SearchResultData
+  results: t.SearchResultData,
+  maxOutputChars?: number
 ): { output: string; references: t.ResultReference[] } {
+  /** Bound highlight content to the per-search budget before formatting */
+  const trimmedHighlights = trimHighlightsToBudget(
+    results,
+    resolveMaxLLMOutputChars(maxOutputChars)
+  );
+
   /** Array to collect all output lines */
   const outputLines: string[] = [];
 
@@ -243,8 +357,11 @@ export function formatResultsForLLM(
     outputLines.push(paaLines.join(''));
   }
 
-  return {
-    output: outputLines.join('\n').trim(),
-    references,
-  };
+  let output = outputLines.join('\n').trim();
+  if (trimmedHighlights > 0) {
+    output += `\n\n_[${trimmedHighlights} additional highlight${
+      trimmedHighlights === 1 ? '' : 's'
+    } omitted to fit the context budget; the cited sources contain the full content.]_`;
+  }
+  return { output, references };
 }

package/src/tools/search/tool.ts

@@ -289,10 +289,12 @@ function createOnSearchResults({
 function createTool({
   schema,
   search,
+  maxOutputChars,
   onSearchResults: _onSearchResults,
 }: {
   schema: Record<string, unknown>;
   search: ReturnType<typeof createSearchProcessor>;
+  maxOutputChars?: number;
   onSearchResults: t.SearchToolConfig['onSearchResults'];
 }): DynamicStructuredTool {
   return tool(
@@ -313,7 +315,7 @@ function createTool({
         }),
       });
       const turn = runnableConfig.toolCall?.turn ?? 0;
-      const { output, references } = formatResultsForLLM(turn, searchResult);
+      const { output, references } = formatResultsForLLM(turn, searchResult, maxOutputChars);
       const data: t.SearchResultData = { turn, ...searchResult, references };
       return [output, { [Constants.WEB_SEARCH]: data }];
     },
@@ -359,6 +361,7 @@ export const createSearchTool = (
     rerankerType = 'cohere',
     topResults = 5,
     maxContentLength,
+    maxOutputChars,
     strategies = ['no_extraction'],
     filterContent = true,
     safeSearch = 1,
@@ -483,6 +486,7 @@ export const createSearchTool = (
   return createTool({
     search,
     schema: toolSchema,
+    maxOutputChars,
     onSearchResults: _onSearchResults,
   });
 };

package/src/tools/search/types.ts

@@ -218,6 +218,13 @@ export interface SearchToolConfig
     ProcessSourcesConfig,
     FirecrawlConfig {
   tavilyScraperOptions?: TavilyScraperConfig;
+  /** Max chars of highlight content this tool feeds the MODEL per search (the
+   * dominant, otherwise-unbounded part of the output). Distinct from
+   * `maxContentLength`, which caps scraped/reranked content per source — full
+   * content always remains in the `WEB_SEARCH` artifact. Defaults to 50,000;
+   * also configurable via the `SEARCH_MAX_LLM_OUTPUT_CHARS` env var. Hosts that
+   * know the context window (e.g. LibreChat) pass a window-relative value. */
+  maxOutputChars?: number;
   logger?: Logger;
   safeSearch?: SafeSearchLevel;
   jinaApiKey?: string;

package/src/tools/subagent/SubagentExecutor.ts

@@ -1,8 +1,9 @@
 import { nanoid } from 'nanoid';
 import { HumanMessage } from '@langchain/core/messages';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
+import type { ChatGeneration, LLMResult } from '@langchain/core/outputs';
 import type { Callbacks } from '@langchain/core/callbacks/manager';
-import type { BaseMessage } from '@langchain/core/messages';
 import type {
   AgentInputs,
   MessageDeltaEvent,
@@ -16,6 +17,7 @@ import type {
   SubagentConfig,
   SubagentUpdateEvent,
   SubagentUpdatePhase,
+  SubagentUsageSink,
   ToolExecuteBatchRequest,
   ToolCallDelta,
   TokenCounter,
@@ -24,7 +26,7 @@ import type { AggregatedHookResult, HookRegistry } from '@/hooks';
 import type { AgentContext } from '@/agents/AgentContext';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
-import { GraphEvents, Callback, StepTypes } from '@/common';
+import { Constants, GraphEvents, Callback, StepTypes } from '@/common';
 import { executeHooks } from '@/hooks';
 
 const DEFAULT_MAX_TURNS = 25;
@@ -236,6 +238,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 class SubagentExecutor {
@@ -248,6 +259,7 @@ export class SubagentExecutor {
   private readonly tokenCounter?: TokenCounter;
   private readonly maxDepth: number;
   private readonly createChildGraph: ChildGraphFactory;
+  private readonly usageSink?: SubagentUsageSink;
   private readonly resolveParentHandlerRegistry?: () =>
     | HandlerRegistry
     | undefined;
@@ -262,6 +274,7 @@ export class SubagentExecutor {
     this.tokenCounter = options.tokenCounter;
     this.maxDepth = options.maxDepth ?? 1;
     this.createChildGraph = options.createChildGraph;
+    this.usageSink = options.usageSink;
     const rawRegistry = options.parentHandlerRegistry;
     if (typeof rawRegistry === 'function') {
       this.resolveParentHandlerRegistry = rawRegistry;
@@ -351,12 +364,35 @@ export class SubagentExecutor {
     const childRunId = `${this.parentRunId}_sub_${nanoid(8)}`;
     const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
 
+    const hostUsageSink = this.usageSink;
     const childGraph = this.createChildGraph({
       runId: childRunId,
       signal: this.parentSignal,
       agents: [childInputs],
       langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
+      /**
+       * Forwarded so the child graph's own `SubagentExecutor` (created in
+       * its `createAgentNode` when `allowNested` keeps subagentConfigs)
+       * reports nested-child usage through the same host sink. Each nesting
+       * level attaches its own capture callback — `workflow.invoke` replaces
+       * the inherited callback chain, so a single top-level handler would
+       * never see grandchild model calls.
+       *
+       * The wrapper rewrites `runId` to THIS executor's parent run: nested
+       * executors emit with their own `parentRunId` (a `*_sub_*` child id),
+       * and each wrapper layer rewrites upward, so by the time an event
+       * reaches the host sink its `runId` is the ROOT run — hosts keying
+       * billing by run id never see intermediate child run ids there
+       * (`subagentRunId` still identifies the emitting child).
+       */
+      subagentUsageSink:
+        hostUsageSink == null
+          ? undefined
+          : /** Returns the host sink's result so async sinks stay awaited
+             *  through every wrapper layer. */
+          (event): void | Promise<void> =>
+            hostUsageSink({ ...event, runId: this.parentRunId }),
     });
 
     let forwarding: ForwarderCallback | undefined;
@@ -402,7 +438,31 @@ export class SubagentExecutor {
        * `runName` gives the child a distinct LangSmith trace root (avoids
        * nested trace pollution).
        */
-      const callbacks: Callbacks = forwarder ? [forwarder] : [];
+      const callbackHandlers: BaseCallbackHandler[] = [];
+      if (forwarder) {
+        callbackHandlers.push(forwarder);
+      }
+      /**
+       * Usage capture rides the same detached callbacks array. Because
+       * `callbacks` REPLACES the inherited chain (see above), the host's
+       * `CHAT_MODEL_END` handler never observes the child's model calls —
+       * this handler is the child-side equivalent of `ModelEndHandler`,
+       * reporting per-call usage to the host's sink for billing.
+       */
+      if (this.usageSink) {
+        callbackHandlers.push(
+          createUsageCaptureHandler({
+            sink: this.usageSink,
+            subagentType,
+            subagentRunId: childRunId,
+            subagentAgentId: childAgentId,
+            parentRunId: this.parentRunId,
+            provider: config.agentInputs.provider,
+            fallbackModel: extractConfiguredModel(config.agentInputs),
+          })
+        );
+      }
+      const callbacks: Callbacks = callbackHandlers;
       /**
        * Inherit the parent's host `configurable` — host-set fields
        * (`requestBody`, `user`, `userMCPAuthMap`, etc.) AND the run-
@@ -719,6 +779,164 @@ export class SubagentExecutor {
   }
 }
 
+/**
+ * Builds the child-run equivalent of a host `CHAT_MODEL_END` handler: a
+ * callback that joins per-call model identity (captured from
+ * `ls_model_name` at chat-model start) with the usage metadata reported at
+ * LLM end, and emits a {@link SubagentUsageEvent} through the host's sink.
+ *
+ * Attached to the child `workflow.invoke` callbacks array, so it observes
+ * every model call inside the child graph — the agent loop and any
+ * auxiliary calls (e.g. child-side summarization). It does NOT observe
+ * deeper subagent levels: each nesting level replaces the callback chain
+ * and attaches its own capture handler via the forwarded
+ * `subagentUsageSink` on the child graph's input.
+ */
+function createUsageCaptureHandler(args: {
+  sink: SubagentUsageSink;
+  subagentType: string;
+  subagentRunId: string;
+  subagentAgentId: string;
+  parentRunId: string;
+  /**
+   * Child config's provider enum — the default tag when a call carries no
+   * `INVOKED_PROVIDER` metadata (hosts key pricing/cache semantics off it).
+   */
+  provider?: string;
+  /**
+   * Child config's model, used when a call carries neither `ls_model_name`
+   * nor `INVOKED_MODEL` metadata.
+   */
+  fallbackModel?: string;
+}): BaseCallbackHandler {
+  const {
+    sink,
+    subagentType,
+    subagentRunId,
+    subagentAgentId,
+    parentRunId,
+    provider,
+    fallbackModel,
+  } = args;
+  /**
+   * Per-call attribution keyed by LangChain callback runId. `model` joins
+   * `ls_model_name` (provider-reported) with `INVOKED_MODEL` (stamped by
+   * `tryFallbackProviders` from the fallback's client options); `provider`
+   * is `INVOKED_PROVIDER`, stamped by `attemptInvoke` with the SDK enum of
+   * the provider that ACTUALLY served the call — correct for
+   * fallback-served calls, where the static config provider would mis-tag
+   * pricing/cache semantics.
+   */
+  const callInfoByCallId = new Map<
+    string,
+    { model?: string; provider?: string }
+  >();
+  const handler = BaseCallbackHandler.fromMethods({
+    handleChatModelStart: (
+      _llm: unknown,
+      _messages: unknown,
+      runId: string,
+      _parentRunId?: string,
+      _extraParams?: Record<string, unknown>,
+      _tags?: string[],
+      metadata?: Record<string, unknown>
+    ): void => {
+      const callModel =
+        asNonEmptyString(metadata?.ls_model_name) ??
+        asNonEmptyString(metadata?.[Constants.INVOKED_MODEL]);
+      const callProvider = asNonEmptyString(
+        metadata?.[Constants.INVOKED_PROVIDER]
+      );
+      if (callModel != null || callProvider != null) {
+        callInfoByCallId.set(runId, {
+          model: callModel,
+          provider: callProvider,
+        });
+      }
+    },
+    handleLLMEnd: async (output: LLMResult, runId: string): Promise<void> => {
+      const callInfo = callInfoByCallId.get(runId);
+      callInfoByCallId.delete(runId);
+      const model = callInfo?.model ?? fallbackModel;
+      const callProvider = callInfo?.provider ?? provider;
+      for (const generationGroup of output.generations) {
+        /**
+         * At most ONE event per generation group: each group is one
+         * provider request (the outer array is per-prompt for batched
+         * calls), and with multiple completions (`n > 1`) every choice in
+         * a group repeats the request-level `usage_metadata` — emitting
+         * per choice would multiply billed tokens.
+         */
+        for (const generation of generationGroup) {
+          const message = (generation as ChatGeneration | undefined)?.message;
+          const usage = (
+            message as { usage_metadata?: UsageMetadata } | undefined
+          )?.usage_metadata;
+          if (usage == null) {
+            continue;
+          }
+          /**
+           * Awaited so async host sinks (billing/persistence) complete
+           * before the model call resolves — `awaitHandlers` only waits on
+           * `handleLLMEnd` itself, so a dropped promise here would let the
+           * parent run finish before usage is recorded and would turn sink
+           * rejections into unhandled rejections.
+           */
+          try {
+            await sink({
+              usage,
+              model,
+              provider: callProvider,
+              subagentType,
+              subagentRunId,
+              subagentAgentId,
+              runId: parentRunId,
+            });
+          } catch {
+            /* observational — a throwing/rejecting host sink must not break the child run */
+          }
+          break;
+        }
+      }
+    },
+    handleLLMError: (_err: unknown, runId: string): void => {
+      callInfoByCallId.delete(runId);
+    },
+  });
+  /**
+   * Dispatch usage synchronously with each model call so all entries are
+   * sunk before `workflow.invoke` resolves — hosts read their accumulator
+   * right after the parent run completes.
+   */
+  handler.awaitHandlers = true;
+  return handler;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+/**
+ * Best-effort read of the configured model from a subagent's client
+ * options. Providers disagree on the key (`model` vs `modelName`), and the
+ * value is only a fallback for calls that carry no `ls_model_name`.
+ */
+function extractConfiguredModel(agentInputs: AgentInputs): string | undefined {
+  const clientOptions = agentInputs.clientOptions as
+    | { model?: unknown; modelName?: unknown }
+    | undefined;
+  if (typeof clientOptions?.model === 'string' && clientOptions.model !== '') {
+    return clientOptions.model;
+  }
+  if (
+    typeof clientOptions?.modelName === 'string' &&
+    clientOptions.modelName !== ''
+  ) {
+    return clientOptions.modelName;
+  }
+  return undefined;
+}
+
 function sanitizeChildConfigurable(
   parentConfigurable: Record<string, unknown> | undefined
 ): Record<string, unknown> {

package/src/types/graph.ts

@@ -3,6 +3,7 @@ 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';
@@ -29,10 +30,10 @@ import type {
   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 {
@@ -89,6 +90,30 @@ export interface AgentLogEvent {
   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,
@@ -104,6 +129,7 @@ export interface EventHandler {
       | SummarizeCompleteEvent
       | SubagentUpdateEvent
       | AgentLogEvent
+      | ContextUsageEvent
       | ToolExecuteBatchRequest
       | { result: ToolEndEvent },
     metadata?: Record<string, unknown>,
@@ -299,6 +325,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 = {
@@ -409,6 +446,62 @@ export interface SubagentUpdateEvent {
   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/src/types/run.ts

@@ -125,6 +125,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,
@@ -242,6 +251,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 = {

package/src/utils/__tests__/apportion.test.ts

@@ -0,0 +1,32 @@
+import { apportionTokenCounts } from '@/utils/tokens';
+
+describe('apportionTokenCounts', () => {
+  it('sums exactly to a ceil-of-sum aggregate despite per-entry fractions', () => {
+    const raw = { add: 33, search: 33, fetch: 33 };
+    const multiplier = 1.4;
+    const target = Math.ceil((33 + 33 + 33) * multiplier);
+    const result = apportionTokenCounts(raw, multiplier, target);
+    const sum = Object.values(result).reduce((acc, count) => acc + count, 0);
+    expect(sum).toBe(target);
+    expect(Object.keys(result).sort()).toEqual(['add', 'fetch', 'search']);
+  });
+
+  it('gives larger remainders priority when distributing leftovers', () => {
+    const result = apportionTokenCounts({ a: 10, b: 19 }, 1.05, 31);
+    expect(result.a + result.b).toBe(31);
+    expect(result.b).toBe(20);
+    expect(result.a).toBe(11);
+  });
+
+  it('handles calibration-style rescaling to an arbitrary target', () => {
+    const counts = { a: 100, b: 200, c: 300 };
+    const target = 451;
+    const result = apportionTokenCounts(counts, target / 600, target);
+    const sum = Object.values(result).reduce((acc, count) => acc + count, 0);
+    expect(sum).toBe(target);
+  });
+
+  it('returns an empty map for no entries', () => {
+    expect(apportionTokenCounts({}, 1.4, 10)).toEqual({});
+  });
+});