@librechat/agents 3.2.34 → 3.2.35

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({});
+  });
+});

package/src/utils/tokens.ts

@@ -395,6 +395,39 @@ export function getTokenCountForMessage(
   return numTokens;
 }
 
+/**
+ * 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 function apportionTokenCounts(
+  rawCounts: Record<string, number>,
+  multiplier: number,
+  targetTotal: number
+): Record<string, number> {
+  const result: Record<string, number> = Object.create(null);
+  const remainders: Array<{ name: string; remainder: number }> = [];
+  let floorSum = 0;
+  for (const [name, rawCount] of Object.entries(rawCounts)) {
+    const scaled = rawCount * multiplier;
+    const floored = Math.floor(scaled);
+    result[name] = floored;
+    floorSum += floored;
+    remainders.push({ name, remainder: scaled - floored });
+  }
+  let leftover = targetTotal - floorSum;
+  if (leftover <= 0 || remainders.length === 0) {
+    return result;
+  }
+  remainders.sort((a, b) => b.remainder - a.remainder);
+  for (let i = 0; leftover > 0; i = (i + 1) % remainders.length) {
+    result[remainders[i].name] += 1;
+    leftover--;
+  }
+  return result;
+}
+
 /**
  * Anthropic's API consistently reports ~10% more tokens than the local
  * claude tokenizer due to internal message framing and content encoding.